{
  "openapi": "3.1.0",
  "info": {
    "title": "YouTube API",
    "version": "1.0.0",
    "description": "YouTube comments extraction exposed through FetchLayer."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/youtube"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/comments": {
      "post": {
        "operationId": "comments",
        "tags": [
          "Comments"
        ],
        "summary": "Extract YouTube comments",
        "description": "Collects top-level comments and nested replies from a YouTube video. Supports sorting by top or newest, configurable reply depth, and pagination through the comment section.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "videoUrl": {
                    "type": "string",
                    "description": "Full YouTube video URL."
                  },
                  "sort": {
                    "type": "string",
                    "description": "Sort order: top (most liked) or newest.",
                    "example": "top"
                  },
                  "depth": {
                    "type": "number",
                    "description": "Levels of replies to include (0 = top-level only, no replies).",
                    "example": "0"
                  },
                  "pages": {
                    "type": "number",
                    "description": "Number of scrolls for more comments.",
                    "example": "1"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "videoUrl",
                  "sort"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                    "sort": "top"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "username": {
                            "type": "string",
                            "description": "Comment author username (with @)."
                          },
                          "comment": {
                            "type": "string",
                            "description": "Full comment text."
                          },
                          "likes": {
                            "type": "number",
                            "description": "Number of likes."
                          },
                          "hasReplies": {
                            "type": "boolean",
                            "description": "Whether this comment has nested replies."
                          },
                          "date": {
                            "type": "string",
                            "description": "Relative date string (e.g. \"1 day ago\")."
                          },
                          "nestedReplies": {
                            "type": "object",
                            "additionalProperties": true,
                            "description": "Nested reply comments (same structure, recursive)."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": [
                      {
                        "username": "@User123",
                        "comment": "Great video!",
                        "likes": 42,
                        "hasReplies": true,
                        "date": "1 day ago",
                        "nestedReplies": [
                          {
                            "username": "@ReplyUser",
                            "comment": "Agreed!",
                            "likes": 5,
                            "hasReplies": false,
                            "date": "1 day ago"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}