{
  "openapi": "3.1.0",
  "info": {
    "title": "Vibe Planet API",
    "description": "API aberta para busca e descoberta de transmissões de áudio de rádios ao vivo do mundo inteiro para agentes de IA e aplicações interativas.",
    "version": "1.0.0",
    "contact": {
      "name": "Vibe Planet",
      "url": "https://vibeplanet.com.br/"
    }
  },
  "servers": [
    {
      "url": "https://de1.api.radio-browser.info/json",
      "description": "Servidor Primário (Alemanha)"
    },
    {
      "url": "https://nl1.api.radio-browser.info/json",
      "description": "Servidor Secundário (Holanda)"
    }
  ],
  "paths": {
    "/stations/topvote/{limit}": {
      "get": {
        "summary": "Obter rádios mais votadas do mundo",
        "description": "Retorna uma lista ordenada com as estações com maior pontuação global.",
        "operationId": "getTopVotedStations",
        "parameters": [
          {
            "name": "limit",
            "in": "path",
            "required": true,
            "description": "Número máximo de estações a retornar (ex: 20, 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 100
            }
          },
          {
            "name": "hidebroken",
            "in": "query",
            "description": "Ocultar estações com falhas conhecidas de streaming",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "is_https",
            "in": "query",
            "description": "Filtrar apenas transmissões seguras via HTTPS",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de estações retornadas com sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RadioStation"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stations/bycountrycodeexact/{countrycode}": {
      "get": {
        "summary": "Obter rádios por código do país",
        "description": "Retorna estações populares filtradas pelo código ISO 3166-1 alpha-2 do país.",
        "operationId": "getStationsByCountryCode",
        "parameters": [
          {
            "name": "countrycode",
            "in": "path",
            "required": true,
            "description": "Código ISO de 2 letras do país (ex: BR, US, FR, JP)",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$",
              "example": "BR"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Quantidade máxima de emissoras",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["votes", "clickcount", "bitrate", "name"],
              "default": "clickcount"
            }
          },
          {
            "name": "reverse",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "hidebroken",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "is_https",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de estações do país informado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RadioStation"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stations/bytag/{tag}": {
      "get": {
        "summary": "Obter rádios por gênero musical ou tag",
        "description": "Retorna rádios associadas a estilos específicos como jazz, rock, lofi, electronic, etc.",
        "operationId": "getStationsByTag",
        "parameters": [
          {
            "name": "tag",
            "in": "path",
            "required": true,
            "description": "Estilo musical ou tag (ex: jazz, rock, lofi, ambient, pop)",
            "schema": {
              "type": "string",
              "example": "jazz"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "votes"
            }
          },
          {
            "name": "reverse",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "hidebroken",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "is_https",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de estações do estilo musical",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RadioStation"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stations/search": {
      "get": {
        "summary": "Buscar rádios por múltiplos critérios",
        "description": "Busca estações combinando termo no nome, país, idioma ou gênero musical.",
        "operationId": "searchStations",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "description": "Termo de busca contido no nome da emissora",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "countrycode",
            "in": "query",
            "description": "Código ISO de 2 letras do país",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "Tag ou gênero musical",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 40
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "clickcount"
            }
          },
          {
            "name": "reverse",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "hidebroken",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "is_https",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resultados da busca",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RadioStation"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RadioStation": {
        "type": "object",
        "properties": {
          "stationuuid": {
            "type": "string",
            "format": "uuid",
            "description": "UUID único da emissora"
          },
          "name": {
            "type": "string",
            "description": "Nome da emissora de rádio"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL original de streaming"
          },
          "url_resolved": {
            "type": "string",
            "format": "uri",
            "description": "URL direta resolvida de áudio para reprodução imediata"
          },
          "homepage": {
            "type": "string",
            "format": "uri"
          },
          "favicon": {
            "type": "string",
            "format": "uri"
          },
          "tags": {
            "type": "string",
            "description": "Gêneros e palavras-chave separadas por vírgula"
          },
          "country": {
            "type": "string"
          },
          "countrycode": {
            "type": "string",
            "description": "Código ISO de 2 letras"
          },
          "state": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "votes": {
            "type": "integer"
          },
          "codec": {
            "type": "string",
            "description": "Formato de codificação do áudio (ex: MP3, AAC)"
          },
          "bitrate": {
            "type": "integer",
            "description": "Taxa de bits em kbps (ex: 128, 192, 320)"
          },
          "hls": {
            "type": "integer",
            "description": "1 se for streaming HLS (.m3u8), 0 caso contrário"
          }
        },
        "required": ["stationuuid", "name", "url_resolved", "country", "countrycode"]
      }
    }
  }
}