{
  "info": {
    "name": "XuniBOX Public API v1",
    "description": "Bộ request mẫu cho REST API công khai của XuniBOX. Đặt biến `api_key` trong Environment trước khi chạy. Tài liệu đầy đủ: https://xunibox.vn/developers",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://xunibox.vn/api/public",
      "type": "string"
    },
    {
      "key": "api_key",
      "value": "",
      "type": "string"
    },
    {
      "key": "track_id",
      "value": "550e8400-e29b-41d4-a716-446655440000",
      "type": "string"
    },
    {
      "key": "artist_id",
      "value": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Danh sách bài nhạc",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/tracks?sort=popular&limit=20&page=1",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "tracks"
          ],
          "query": [
            {
              "key": "sort",
              "value": "popular",
              "description": "newest | oldest | popular | title_asc | title_desc"
            },
            {
              "key": "limit",
              "value": "20",
              "description": "1-100, mặc định 20"
            },
            {
              "key": "page",
              "value": "1",
              "description": "1-5000, mặc định 1"
            }
          ]
        },
        "description": "Trả về kho nhạc theo trang. Dùng cho tab 'Phổ biến' hoặc 'Mới nhất' trong màn hình chọn nhạc."
      },
      "response": []
    },
    {
      "name": "Tìm kiếm bài nhạc",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/tracks?q=lofi&limit=20",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "tracks"
          ],
          "query": [
            {
              "key": "q",
              "value": "lofi",
              "description": "Từ khóa tìm kiếm, tối đa 100 ký tự"
            },
            {
              "key": "limit",
              "value": "20",
              "description": "Số kết quả mỗi trang"
            }
          ]
        },
        "description": "Tìm đồng thời trong title, artist và genre."
      },
      "response": []
    },
    {
      "name": "Lọc theo thể loại / nghệ sĩ",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/tracks?genre=Pop&artist=&artist_id={{artist_id}}&title=&sort=newest",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "tracks"
          ],
          "query": [
            {
              "key": "genre",
              "value": "Pop",
              "description": "Tìm một phần thể loại, tối đa 80 ký tự"
            },
            {
              "key": "artist",
              "value": "",
              "description": "Tìm một phần tên nghệ sĩ, tối đa 120 ký tự"
            },
            {
              "key": "artist_id",
              "value": "{{artist_id}}",
              "description": "UUID nghệ sĩ, lọc chính xác"
            },
            {
              "key": "title",
              "value": "",
              "description": "Tìm một phần tên bài hát, tối đa 160 ký tự"
            },
            {
              "key": "sort",
              "value": "newest",
              "description": "newest | oldest | popular | title_asc | title_desc"
            }
          ]
        },
        "description": "Kết hợp nhiều bộ lọc (phép AND). Dùng artist_id lấy từ /artists để lọc chính xác thay vì lọc theo tên."
      },
      "response": []
    },
    {
      "name": "Chi tiết bài nhạc",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/tracks/{{track_id}}",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "tracks",
            "{{track_id}}"
          ]
        },
        "description": "Lấy metadata đầy đủ của một bài nhạc. Không tăng play_count."
      },
      "response": []
    },
    {
      "name": "Làm mới link nghe thử",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/tracks/{{track_id}}/audio-url",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "tracks",
            "{{track_id}}",
            "audio-url"
          ]
        },
        "description": "Gọi ngay trước khi phát hoặc trước khi render video để lấy audio_url đã ký còn hạn. Trả thêm cover_url, preview_duration_seconds, media_expires_in và expires_at. Không cache link cứng."
      },
      "response": []
    },
    {
      "name": "Lấy nhiều bài nhạc theo ID",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/tracks/by-ids?ids={{track_id}}",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "tracks",
            "by-ids"
          ],
          "query": [
            {
              "key": "ids",
              "value": "{{track_id}}",
              "description": "Danh sách UUID phân tách bằng dấu phẩy"
            }
          ]
        },
        "description": "Làm mới hàng loạt media URL, tối đa 50 UUID mỗi lần."
      },
      "response": []
    },
    {
      "name": "Danh sách thể loại",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/genres",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "genres"
          ]
        },
        "description": "Các thể loại đang có trong kho nhạc, dùng để dựng tab lọc."
      },
      "response": []
    },
    {
      "name": "Danh sách nghệ sĩ",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/artists?q=&limit=20&page=1",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "artists"
          ],
          "query": [
            {
              "key": "q",
              "value": "",
              "description": "Từ khóa tên nghệ sĩ"
            },
            {
              "key": "limit",
              "value": "20",
              "description": "Số kết quả mỗi trang"
            },
            {
              "key": "page",
              "value": "1",
              "description": "Trang hiện tại"
            }
          ]
        },
        "description": "Duyệt hoặc tìm nghệ sĩ theo tên."
      },
      "response": []
    },
    {
      "name": "Bài nhạc theo nghệ sĩ",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/artists/{{artist_id}}/tracks",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "artists",
            "{{artist_id}}",
            "tracks"
          ]
        },
        "description": "Danh sách bài nhạc của một nghệ sĩ."
      },
      "response": []
    },
    {
      "name": "Health check",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/healthz",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "healthz"
          ]
        },
        "description": "Không cần API key. Trả phiên bản API, trạng thái hệ thống và thời gian phản hồi."
      },
      "response": []
    },
    {
      "name": "Readiness check",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/readyz",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "readyz"
          ]
        },
        "description": "Không cần API key. Trả ready/not_ready, timestamp, từng check và lý do nếu chưa sẵn sàng."
      },
      "response": []
    },
    {
      "name": "Trạng thái vận hành",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/status",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "status"
          ]
        },
        "description": "Không cần API key. Thống kê kho nhạc và cấu hình rate limit hiện tại."
      },
      "response": []
    },
    {
      "name": "Metrics (Prometheus)",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-Key",
            "value": "{{api_key}}",
            "type": "text"
          },
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/metrics",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "metrics"
          ]
        },
        "description": "Không cần API key. Định dạng text exposition 0.0.4 để scrape."
      },
      "response": []
    }
  ]
}