{
  "openapi": "3.0.3",
  "info": {
    "title": "TubExperto API",
    "description": "Query YouTube experts using AI-powered knowledge bases built from channel transcripts. Each expert represents a YouTube channel with indexed and embedded video content, enabling RAG-powered question answering.",
    "version": "1.1.0",
    "contact": {
      "name": "TubExperto",
      "url": "https://tubexperto.com"
    }
  },
  "servers": [
    {
      "url": "https://tubexperto.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/mcp/user/experts": {
      "get": {
        "operationId": "listMyExperts",
        "summary": "List my subscribed experts",
        "description": "Returns the authenticated user's personal list of YouTube expert subscriptions, including their channels, video counts, and topics. Use this to discover what experts are available before querying them.",
        "responses": {
          "200": {
            "description": "User's expert subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "experts": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ExpertDetail" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/experts/query-all": {
      "post": {
        "operationId": "queryAllExperts",
        "summary": "Ask all my experts at once",
        "description": "Cross-expert RAG query: asks all the user's subscribed experts simultaneously and returns combined knowledge. More comprehensive than querying a single expert. Costs 2 credits.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["question"],
                "properties": {
                  "question": {
                    "type": "string",
                    "description": "The question to ask all experts"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Combined answer from all experts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": { "type": "string" },
                    "expertsQueried": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/experts/search": {
      "get": {
        "operationId": "listExperts",
        "summary": "Search for experts",
        "description": "Search for YouTube experts by topic, category, or keyword. Returns experts with their channel info and available video counts.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Search query (e.g., 'marketing', 'growth hacking')"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 10, "maximum": 50 },
            "description": "Maximum results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching experts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "experts": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ExpertSummary" }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/experts/query": {
      "post": {
        "operationId": "queryExpert",
        "summary": "Ask an expert a question",
        "description": "Ask a question to a specific YouTube expert. Uses RAG (Retrieval-Augmented Generation) to find relevant video segments and generate an informed answer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["expertId", "question"],
                "properties": {
                  "expertId": {
                    "type": "string",
                    "description": "Expert ID or slug"
                  },
                  "question": {
                    "type": "string",
                    "description": "The question to ask"
                  },
                  "context": {
                    "type": "string",
                    "description": "Optional context for more personalized answers"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Expert's answer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "expert": { "$ref": "#/components/schemas/ExpertSummary" },
                    "question": { "type": "string" },
                    "answer": { "type": "string" },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "segmentsUsed": { "type": "integer" },
                        "contextProvided": { "type": "boolean" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/experts/{expertId}": {
      "get": {
        "operationId": "getExpertInfo",
        "summary": "Get expert details",
        "description": "Get detailed information about a YouTube expert including their topics, channel statistics, and description.",
        "parameters": [
          {
            "name": "expertId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Expert ID or slug"
          }
        ],
        "responses": {
          "200": {
            "description": "Expert details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ExpertDetail" }
              }
            }
          }
        }
      }
    },
    "/api/mcp/experts/{expertId}/videos": {
      "get": {
        "operationId": "listExpertVideos",
        "summary": "List expert's videos",
        "description": "Get paginated list of videos indexed for an expert.",
        "parameters": [
          {
            "name": "expertId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 20, "maximum": 100 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of videos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "expert": { "$ref": "#/components/schemas/ExpertSummary" },
                    "videos": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Video" }
                    },
                    "pagination": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/channels/{channelId}/latest": {
      "get": {
        "operationId": "getLatestChannelVideos",
        "summary": "Get latest channel videos",
        "description": "Get the most recent videos from a YouTube channel via RSS feed (zero API quota usage).",
        "parameters": [
          {
            "name": "channelId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "YouTube channel ID"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 10, "maximum": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "Latest videos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "channelId": { "type": "string" },
                    "channelName": { "type": "string" },
                    "videos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "videoId": { "type": "string" },
                          "title": { "type": "string" },
                          "publishedAt": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp/videos/{videoId}/summary": {
      "get": {
        "operationId": "getVideoSummary",
        "summary": "Get video summary",
        "description": "Get a video summary with chapters, key topics, and analysis. Generates on-demand if not cached (may take a few seconds).",
        "parameters": [
          {
            "name": "videoId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "YouTube video ID"
          },
          {
            "name": "expertId",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Expert ID for context-aware summary"
          },
          {
            "name": "locale",
            "in": "query",
            "schema": { "type": "string", "default": "es", "enum": ["es", "en"] },
            "description": "Language for the summary"
          }
        ],
        "responses": {
          "200": {
            "description": "Video summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VideoSummary" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from https://tubexperto.com/settings/api"
      }
    },
    "schemas": {
      "ExpertSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" }
        }
      },
      "ExpertDetail": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "topics": { "type": "array", "items": { "type": "string" } },
          "videoCount": { "type": "integer" },
          "subscriberCount": { "type": "integer" }
        }
      },
      "Video": {
        "type": "object",
        "properties": {
          "video_id": { "type": "string" },
          "title": { "type": "string" },
          "thumbnail": { "type": "string" },
          "duration": { "type": "string" },
          "published_at": { "type": "string" }
        }
      },
      "VideoSummary": {
        "type": "object",
        "properties": {
          "videoId": { "type": "string" },
          "title": { "type": "string" },
          "chapters": { "type": "array", "items": { "type": "object" } },
          "analysis": { "type": "object" },
          "locale": { "type": "string" }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" }
        }
      }
    }
  }
}