Documentation Index

Base URL

https://youtube-music.f8team.dev/api

Authentication

Đăng nhập

POST /auth/login

Body:

{
  "email": "dia-chi-email",
  "password": "mat-khau"
}

Response:

{
  "access_token": "token",
  "refresh_token": "token",
  "user": {
    "id": 1,
    "name": "My user",
    "email": "[email protected]",
    "created_at": "thoigian",
    "updated_at": "thoigian"
  }
}

Đăng ký

POST /auth/register

Body:

{
  "name": "Ten",
  "email": "dia-chi-email",
  "password": "mat-khau",
  "confirmPassword": "mat-khau"
}

Response:

{
  "access_token": "token",
  "refresh_token": "token",
  "user": {
    "id": 1,
    "name": "My user",
    "email": "[email protected]",
    "created_at": "thoigian",
    "updated": "thoigian"
  }
}

Lấy thông tin cá nhân

GET /auth/me

Header:

Authorization: Bearer <token>

Response:

{
  "id": 1,
  "name": "My user",
  "email": "[email protected]",
  "created_at": "thoigian",
  "updated": "thoigian"
}

Đăng xuất

DELETE /auth/logout

Header:

Authorization: Bearer <token>

Response:

{
  "success": true,
  "message": "Logout successfuly"
}

Refresh Token

POST /auth/refresh-token

Body:

{
  "refreshToken": "refresh-token"
}

Response

{
  "access_token": "token",
  "refresh_token": "token"
}

Cập nhật thông tin cá nhân

PATCH /auth/me

Header:

Authorization: Bearer <token>

Body:

{
  "name": "ten",
  "email": "email"
}

Response:

{
  "success": true,
  "message": "Update profile successfuly"
}

Đổi mật khẩu

PATCH /auth/change-password

Header:

Authorization: Bearer <token>

Body:

{
  "oldPassword": "old password",
  "password": "new password",
  "confirmPassword": "confirm new password"
}

Response:

{
  "success": true,
  "message": "Change password successfuly"
}

Tâm trạng và thể loại

Lấy danh sách tâm trạng

GET /categories

Response:

{
  "items": [
    {
      "_id": "691cbe6edd97648f59757bed",
      "slug": "nh-c-ballad",
      "__v": 0,
      "color": "#FFDAC1",
      "createdAt": "2025-11-18T18:43:57.998Z",
      "description": "Nhạc Ballad tuyển chọn những bản nhạc phù hợp",
      "name": "Nhạc Ballad",
      "thumbnailUrl": "https://picsum.photos/seed/category-2/400/240",
      "type": "genre",
      "updatedAt": "2025-11-18T18:43:57.998Z"
    },
    {
      "_id": "691cbe6edd97648f59757bf6",
      "slug": "nh-c-bu-n-v1",
      "__v": 0,
      "color": "#E2F0CB",
      "createdAt": "2025-11-18T18:43:57.998Z",
      "description": "Nhạc Buồn tuyển chọn những bản nhạc phù hợp",
      "name": "Nhạc Buồn",
      "thumbnailUrl": "https://picsum.photos/seed/category-11/400/240",
      "type": "mood",
      "updatedAt": "2025-11-18T18:43:57.998Z"
    }
  ]
}

Chi tiết tâm trạng

GET /categories/:slug

Query parameters:

subLimit (number, optional) — số lượng chuyên mục con tối đa trả về. Default: 10.
playlistLimit (number, optional) — số playlist tối đa trả về cho mỗi chuyên mục con. Default: 6.
subSort (string, optional) — cách sắp xếp chuyên mục con. Hỗ trợ: name (mặc định) hoặc popularity.
playlistSort (string, optional) — cách sắp xếp playlist trong mỗi chuyên mục con. Hỗ trợ: popularity (mặc định), recent.

Response:

{
  "_id": "691cbe6edd97648f59757bf5",
  "slug": "nh-c-lofi-v1",
  "__v": 0,
  "color": "#FFDAC1",
  "createdAt": "2025-11-18T18:43:57.998Z",
  "description": "Nhạc Lofi tuyển chọn những bản nhạc phù hợp",
  "name": "Nhạc Lofi",
  "thumbnailUrl": "https://picsum.photos/seed/category-10/400/240",
  "type": "mood",
  "updatedAt": "2025-11-18T18:43:57.998Z",
  "subcategories": [
    {
      "_id": "691cbe6edd97648f59757c33",
      "slug": "nh-c-lofi-acoustic",
      "__v": 0,
      "color": "#FFDAC1",
      "createdAt": "2025-11-18T18:43:58.112Z",
      "name": "Nhạc Lofi Acoustic",
      "parentSlug": "nh-c-lofi-v1",
      "popularity": 508,
      "thumbnailUrl": "https://picsum.photos/seed/sub-10-3/320/180",
      "updatedAt": "2025-11-18T18:43:58.112Z",
      "playlists": [
        {
          "_id": "691cc277cfac3e99da7fe89a",
          "title": "Nhạc Lofi Acoustic - Tuyển chọn 1",
          "slug": "nh-c-lofi-acoustic-nh-c-lofi-acoustic-tuy-n-ch-n-1",
          "subcategorySlug": "nh-c-lofi-acoustic",
          "description": "Nhạc Lofi Acoustic tuyển chọn",
          "thumbnails": [
            "https://picsum.photos/seed/pl-nh-c-lofi-acoustic-0/640/360"
          ],
          "popularity": 777,
          "artists": [],
          "tracks": [],
          "__v": 0,
          "createdAt": "2025-11-18T19:01:11.545Z",
          "updatedAt": "2025-11-18T19:01:11.545Z"
        },
        {
          "_id": "691cc277cfac3e99da7fe89b",
          "title": "Nhạc Lofi Acoustic - Tuyển chọn 2",
          "slug": "nh-c-lofi-acoustic-nh-c-lofi-acoustic-tuy-n-ch-n-2",
          "subcategorySlug": "nh-c-lofi-acoustic",
          "description": "Nhạc Lofi Acoustic tuyển chọn",
          "thumbnails": [
            "https://picsum.photos/seed/pl-nh-c-lofi-acoustic-1/640/360"
          ],
          "popularity": 758,
          "artists": [],
          "tracks": [],
          "__v": 0,
          "createdAt": "2025-11-18T19:01:11.545Z",
          "updatedAt": "2025-11-18T19:01:11.545Z"
        }
      ]
    }
  ]
}

Lấy danh sách dòng nhạc

GET /lines

Query parameters:

limit: - Số lượng dòng nhạc tối đa. Default 50

Response:

{
  "items": [
    {
      "_id": "691cbe6edd97648f59757c69",
      "slug": "bu-n-1",
      "__v": 0,
      "color": "#FFD6A5",
      "createdAt": "2025-11-18T18:43:58.306Z",
      "description": "Buồn 1 — playlist và tuyển chọn",
      "name": "Buồn 1",
      "thumbnailUrl": "https://picsum.photos/seed/line-7/480/270",
      "updatedAt": "2025-11-18T18:43:58.306Z"
    },
    {
      "_id": "691cbe6edd97648f59757c7d",
      "slug": "bu-n-2",
      "__v": 0,
      "color": "#FFD6A5",
      "createdAt": "2025-11-18T18:43:58.306Z",
      "description": "Buồn 2 — playlist và tuyển chọn",
      "name": "Buồn 2",
      "thumbnailUrl": "https://picsum.photos/seed/line-27/480/270",
      "updatedAt": "2025-11-18T18:43:58.306Z"
    }
  ]
}

Lấy chi tiết dòng nhạc

GET /lines/:slug

Response:

{
  "_id": "691cbe6edd97648f59757c69",
  "slug": "bu-n-1",
  "__v": 0,
  "color": "#FFD6A5",
  "createdAt": "2025-11-18T18:43:58.306Z",
  "description": "Buồn 1 — playlist và tuyển chọn",
  "name": "Buồn 1",
  "thumbnailUrl": "https://picsum.photos/seed/line-7/480/270",
  "updatedAt": "2025-11-18T18:43:58.306Z"
}

Lấy danh sách bài hát theo dòng

GET /lines/:slug/songs

Query Parameters

limit (number, optional) — số lượng tối đa trả về. Mặc định 20.
sort (string, optional) — trường để sắp xếp. Ví dụ: views, -views, title, -title, popularity, -popularity. Mặc định -popularity.

Response

{
  "items": [
    {
      "name": "Buồn Tuyển Tập 5",
      "thumb": "https://picsum.photos/seed/song-bu-n-1-4/640/360",
      "views": 935,
      "albumName": null
    },
    {
      "name": "Buồn Tuyển Tập 3",
      "thumb": "https://picsum.photos/seed/song-bu-n-1-2/640/360",
      "views": 153,
      "albumName": null
    }
  ]
}

Lấy danh sách phát nổi bật theo dòng

GET /lines/:slug/playlists

Query Parameters

:slug (string) — slug của dòng nhạc.
Query params:
limit (number, optional) — số lượng tối đa trả về. Mặc định 20.
sort (string, optional) — trường để sắp xếp; ví dụ popularity, -popularity, title.
Để lấy playlist gần đây nhất, dùng sort=-createdAt.
Mặc định: -popularity.

Lấy danh sách Album theo dòng nhạc

GET /lines/:slug/albums

Query Parameters

limit (number, optional) — số lượng tối đa trả về. Mặc định 20.
sort (string, optional) — trường để sắp xếp; ví dụ popularity, -popularity, releaseDate, -releaseDate, title.
Ghi chú: để lấy album gần đây nhất, dùng sort=-releaseDate hoặc sort=-createdAt.
Mặc định: -popularity.

Lấy danh sách video cho dòng nhạc

GET /lines/:slug/videos

Query params:

limit (number, optional) — số lượng tối đa trả về. Mặc định 20.
sort (string, optional) — trường để sắp xếp; ví dụ popularity, -popularity, views, -views, title.
Ghi chú: để lấy video gần đây nhất, dùng sort=-createdAt.
Mặc định: -popularity.

Khám phá

Lấy album mới nhất

GET /explore/albums

Query params:

limit (number) — Số lượng items (default 10)

Lấy video mới nhất

GET /explore/videos

Query params:

limit (number) — Số lượng items (default 10)

Lấy danh sách tâm trạng và thể loại (Tổng hợp)

GET /explore/meta

Bản phát hành mới

GET /explore/new-releases

Query params:

limit (number) — Số lượng tối đa, default 20
sort (string) — Sắp xếp theo trường, tiền tố - sắp xếp giảm dần, + tăng dần. Default -releaseDate.

Bảng xếp hạng

Bảng xếp hạng video

GET /charts/videos

Query parameters:

country (string) — eg. GLOBAL, US, VN. Default: GLOBAL. - period (string) — Thời gian (eg. 2025-11-18), or latest. Default: latest.
limit (number) tổng số items. Default: 50.
sort (string) — Sắp xếp, e.g. -views or -popularity. Default: -views.

Bảng xếp hạng nghệ sỹ

GET /charts/top-artists

Query parameters:

country (string) — default GLOBAL.
period (string) — e.g. latest.
limit (number) — default 20.

Danh sách quốc gia

GET /charts/countries

Response:

{
  "countries": [
    {
      "code": "GLOBAL",
      "name": "Global"
    },
    {
      "code": "VN",
      "name": "Vietnam"
    }
  ]
}

Danh mục trang chủ

Lấy danh sách danh mục trang chủ

GET /moods

Query Params:

limit (default 20) sort (default -popularity)

Lấy chi tiết danh mục

GET /moods/:slug

Lấy Quick Pick

GET /quick-picks

Query params:

mood (string) — Slug của danh mục trang chủ (e.g. relax).
country (string) — country code, default GLOBAL.
limit (number) — Số lượng items trả về (default 12)

Trang chủ

Gợi ý Album

GET /home/albums-for-you

Query params:
country (string) — default GLOBAL.
limit (number) — default 12.

Lấy danh sách Todays Hit

GET /home/todays-hits

Query params:

country (string) — default GLOBAL.
limit (number) — default 12.

Lấy danh sách phát theo quốc gia

GET /playlists/by-country?country={code}&limit={n}

country (string) — e.g. VN, default GLOBAL.
limit (number) — default 12.

Danh sách gợi ý theo lịch sử

GET /home/personalized

Query Params:

limit: Giới hạn số lượng

Header: Authorization: Bearer <access_token>

Ghi lại lịch sử nghe

POST /events/play

Header: Authorization: Bearer <access_token>

Body:

Một trong các songId, albumId, hoặc playlistId.

Tùy chọn playedAt ISO timestamp

Chi tiết Playlist

GET /playlists/details/:slug

Query params:

limit (number) — Số lượng track tối đa trả về (default 200)

Chi tiết Album

GET /albums/details/:slug

Query params:

limit (number) — số lượng tối đa trả về. Mặc định 20.
sort (string) — trường sắp xếp, có thể dùng tiền tố - (giảm dần) hoặc + (tăng dần). Ví dụ: -popularity, +releaseDate, -createdAt.

Chi tiết video

GET /videos/details/:id

Query params:

limit (number, optional) — Số lượng trả về tối đa (default: 20)

Chi tiết bài hát

GET /songs/details/:id

Query params:

limit (number, optional) — Số lượng trả về tối đa (default: 20)

Tìm kiếm

Gợi ý tìm kiếm

GET /search/suggestions

Params

q: Từ khóa

Kết quả tìm kiếm

GET /search

Params:

q (string, required): tìm kiếm theo tiêu đề (case-insensitive, contains match).
limit (number, optional): số lượng kết quả trên trang (mặc định 20).
page (number, optional): số trang (mặc định 1).