{
  "openapi": "3.0.3",
  "info": {
    "title": "YouTube Search API",
    "description": "SearchApi.io YouTube Search endpoint",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.aisa.one/apis/v1",
      "description": "YouTube Search API Server"
    }
  ],
  "paths": {
    "/youtube/search": {
      "get": {
        "x-aisa-pricing": {
          "model": "per_request",
          "currency": "USD",
          "price_usd": 0.0029,
          "cost_tier": "low"
        },
        "summary": "YouTube Search",
        "operationId": "get_youtube_search",
        "description": "Search YouTube and get back matching videos, channels, and playlists. Set `engine=youtube` and pass the query in `q`; both are required. Optionally narrow by country (`gl`) and interface language (`hl`), or pass a YouTube filter token in `sp` for pagination and advanced filters such as upload date, duration, or result type. Use this to find video content on a topic, track a channel's recent uploads, or gauge how much video coverage a subject has. Note: this is served through the AIsa mapped path `/apis/v1/youtube/search`; the upstream provider's canonical path is not mounted directly.",
        "tags": [
          "YouTube Search"
        ],
        "parameters": [
          {
            "name": "engine",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "youtube"
              ]
            },
            "description": "SearchApi engine identifier. Use `youtube` for this YouTube endpoint."
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search query. Required by runtime and upstream SearchApi."
          },
          {
            "name": "sp",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "YouTube filter token (pagination or advanced filters)"
          },
          {
            "name": "gl",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Country code (e.g. us, jp)"
          },
          {
            "name": "hl",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Interface language"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful YouTube search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "YouTube search result payload returned by SearchApi through the AIsa wrapper.",
                  "additionalProperties": true,
                  "properties": {
                    "search_metadata": {
                      "type": "object",
                      "additionalProperties": true,
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "request_time_taken": {
                          "type": "number"
                        },
                        "parsing_time_taken": {
                          "type": "number"
                        },
                        "total_time_taken": {
                          "type": "number"
                        },
                        "request_url": {
                          "type": "string"
                        },
                        "html_url": {
                          "type": "string"
                        },
                        "json_url": {
                          "type": "string"
                        }
                      }
                    },
                    "search_parameters": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "search_information": {
                      "type": "object",
                      "additionalProperties": true,
                      "properties": {
                        "total_results": {
                          "type": "integer"
                        }
                      }
                    },
                    "videos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "position": {
                            "type": "integer"
                          },
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "link": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "thumbnail": {
                            "type": "string"
                          },
                          "published_time": {
                            "type": "string"
                          },
                          "length": {
                            "type": "string"
                          },
                          "views": {
                            "oneOf": [
                              {
                                "type": "integer"
                              },
                              {
                                "type": "string"
                              }
                            ]
                          },
                          "channel": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "is_live": {
                            "type": "boolean"
                          },
                          "badges": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "channels": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "position": {
                            "type": "integer"
                          },
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "link": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "thumbnail": {
                            "type": "string"
                          },
                          "subscribers": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "shorts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "position": {
                            "type": "integer"
                          },
                          "section_title": {
                            "type": "string"
                          },
                          "items": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          }
                        }
                      }
                    },
                    "sections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "position": {
                            "type": "integer"
                          },
                          "section_title": {
                            "type": "string"
                          },
                          "items": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          }
                        }
                      }
                    },
                    "playlists": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "ads": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "additionalProperties": true,
                      "properties": {
                        "next_page_token": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters"
          },
          "401": {
            "description": "Unauthorized / Invalid API key"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}