Muse API Documentation

Complete API specification for the Muse music streaming platform

Made with love by @nyumat

Authentication

Most of the Muse API uses JWT tokens for authentication. To authorize your client, include a token in the Authorization header:

Authorization: Bearer <your_jwt_token>
POST /auth/register

Register a new user account.

// Request Body
{
    "email": "string",
    "password": "string",
    "name": "string",
    "username": "string"
}

// Response Example
{
    "message": "User created successfully",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
POST /auth/login

Authenticate a user and receive a JWT token.

// Request Body
{
    "username": "string",
    "password": "string"
}

// Response Example
{
    "message": "Login successful",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Songs

GET /api/songs

Retrieve all songs for the authenticated user.

// Response Example
[{
    "_id": "65fb1234c8e123456789abcd",
    "title": "Never Gonna Give You Up",
    "duration": 213,
    "mediaUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "r2Key": "songs/7fc913eb8c07b8e144ea62fc33e4c03e.mp3",
    "createdBy": "65fb1234c8e123456789abce",
    "upload_date": "1711321213",
    "view_count": 1234567890,
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "tags": ["pop", "80s"],
    "original_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "stream_url": "https://muse-songs.r2.cloudflarestorage.com/songs/...",
    "extractor": "youtube",
    "duration_string": "3:33",
    "ytdlp_id": "dQw4w9WgXcQ",
    "uploader": "Rick Astley",
    "listeningTime": 1800,
    "createdAt": "2024-03-20T12:00:00.000Z",
    "updatedAt": "2024-03-20T12:00:00.000Z"
}]
POST /api/songs

Upload a new song from a supported platform (YouTube, SoundCloud).

// Request Body
{
    "mediaUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

// Response Example
{
    "message": "Song uploaded successfully",
    "songId": "65fb1234c8e123456789abcd"
}
GET /api/songs/:id/stream

Get a temporary streaming URL for a song.

// Response Example
{
    "url": "https://muse-songs.r2.cloudflarestorage.com/songs/7fc913eb8c07b8e144ea62fc33e4c03e.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
}
GET /api/songs/:type

Get songs by platform type (youtube, soundcloud).

// Response Example
[{
    "_id": "65fb1234c8e123456789abcd",
    "title": "Never Gonna Give You Up",
    "duration": 213,
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "stream_url": "https://muse-songs.r2.cloudflarestorage.com/songs/...",
    "uploader": "Rick Astley",
    "listeningTime": 1800
}]
POST /api/songs/:id/listen

Update listening time for a song.

// Request Body
{
    "time": 300  // 5 minutes in seconds
}

// Response Example
{
    "message": "Listening time updated"
}

Playlists

GET /api/playlists

Get all playlists for the authenticated user.

// Response Example
[{
    "_id": "65fb1234c8e123456789abcd",
    "name": "80s Hits",
    "description": "Best songs from the 80s",
    "coverImage": "https://muse-covers.r2.cloudflarestorage.com/covers/...",
    "visibility": "public",
    "createdBy": {
        "_id": "65fb1234c8e123456789abce",
        "username": "musiclover"
    },
    "songs": [{
        "_id": "65fb1234c8e123456789abcd",
        "title": "Never Gonna Give You Up",
        "duration": 213,
        "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
        "stream_url": "https://muse-songs.r2.cloudflarestorage.com/songs/..."
    }],
    "playCount": 42,
    "createdAt": "2024-03-20T12:00:00.000Z",
    "updatedAt": "2024-03-20T12:00:00.000Z"
}]
GET /api/playlists/:id

Get a specific playlist.

// Response Example
{
    "_id": "65fb1234c8e123456789abcd",
    "name": "80s Hits",
    "description": "Best songs from the 80s",
    "coverImage": "https://muse-covers.r2.cloudflarestorage.com/covers/abc123.jpg",
    "visibility": "public",
    "createdBy": {
        "_id": "65fb1234c8e123456789abce",
        "username": "musiclover"
    },
    "songs": [{
        "_id": "65fb1234c8e123456789abcd",
        "title": "Never Gonna Give You Up",
        "duration": 213,
        "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
        "stream_url": "https://muse-songs.r2.cloudflarestorage.com/songs/..."
    }],
    "playCount": 42,
    "createdAt": "2024-03-20T12:00:00.000Z",
    "updatedAt": "2024-03-20T12:00:00.000Z"
}
PUT /api/playlists/:id

Update a playlist.

// Request Body (multipart/form-data)
{
    "name": "90s Hits",
    "description": "Best songs from the 90s",
    "isPublic": true,
    "cover": File  // Optional
}

// Response Example
{
    "_id": "65fb1234c8e123456789abcd",
    "name": "90s Hits",
    "description": "Best songs from the 90s",
    "coverImage": "https://muse-covers.r2.cloudflarestorage.com/covers/xyz789.jpg",
    "visibility": "public",
    "createdBy": {
        "_id": "65fb1234c8e123456789abce",
        "username": "musiclover"
    },
    "songs": [...],
    "playCount": 42,
    "updatedAt": "2024-03-20T12:30:00.000Z"
}
GET /api/playlists/:userId/most-played

Get user's most played playlists.

// Response Example
[{
    "_id": "65fb1234c8e123456789abcd",
    "name": "80s Hits",
    "description": "Best songs from the 80s",
    "coverImage": "https://muse-covers.r2.cloudflarestorage.com/covers/abc123.jpg",
    "playCount": 150,
    "songs": [{
        "_id": "65fb1234c8e123456789abcd",
        "title": "Never Gonna Give You Up",
        "stream_url": "https://muse-songs.r2.cloudflarestorage.com/songs/..."
    }]
}]
POST /api/playlists/:id/songs

Add a song to a playlist.

// Request Body
{
    "songId": "65fb1234c8e123456789abcd"
}

// Response Example
{
    "_id": "65fb1234c8e123456789abcd",
    "name": "80s Hits",
    "songs": [{
        "_id": "65fb1234c8e123456789abcd",
        "title": "Never Gonna Give You Up",
        "stream_url": "https://muse-songs.r2.cloudflarestorage.com/songs/..."
    }],
    "updatedAt": "2024-03-20T12:30:00.000Z"
}

Users

GET /users

Get all users (excluding passwords).

// Response Example
    [{
        "_id": "65fb1234c8e123456789abce",
        "username": "musiclover",
        "email": "user@example.com",
        "name": "Music Lover",
        "pfp": "https://muse-pfp.r2.cloudflarestorage.com/pfp/abc123.jpg",
        "bio": "I love music!",
        "songs": [{
            "_id": "65fb1234c8e123456789abcd",
            "title": "Never Gonna Give You Up"
        }],
        "createdAt": "2024-03-20T12:00:00.000Z"
    }]
GET /users/data/stats

Get user statistics.

// Response Example
    {
        "totalDownloads": 42,
        "storageUsed": "128.45",  // in MB
        "totalPlaylists": 5,
        "totalListeningTime": "24.5"  // in hours
    }
PUT /auth/update

Update user profile.

// Request Body (multipart/form-data)
    {
        "username": "newusername",
        "email": "newemail@example.com",
        "name": "New Name",
        "bio": "New bio",
        "password": "newpassword",
        "pfp": File  // Optional profile picture
    }

    // Response Example
    {
        "updatedUser": {
            "_id": "65fb1234c8e123456789abce",
            "username": "newusername",
            "email": "newemail@example.com",
            "name": "New Name",
            "pfp": "https://muse-pfp.r2.cloudflarestorage.com/pfp/xyz789.jpg",
            "bio": "New bio",
            "updatedAt": "2024-03-20T12:30:00.000Z"
        },
        "newToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
POST /users/media/favorite/:type

Mark a song or playlist as favorite.

// Request Body
    {
        "itemId": "65fb1234c8e123456789abcd"
    }

    // Response Example
    {
        "message": "Playlist favorited successfully!"  // or "Song favorited successfully!"
    }
GET /users/media/favorite/:type

Get user's favorite songs or playlists.

// Response Example
    {
        "favoritePlaylists": [{
            "_id": "65fb1234c8e123456789abcd",
            "name": "80s Hits",
            "description": "Best songs from the 80s",
            "coverImage": "https://muse-covers.r2.cloudflarestorage.com/covers/abc123.jpg",
            "visibility": "public",
            "createdBy": {
                "_id": "65fb1234c8e123456789abce",
                "username": "musiclover"
            },
            "songs": [{
                "_id": "65fb1234c8e123456789abcd",
                "title": "Never Gonna Give You Up",
                "duration": 213,
                "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
                "stream_url": "https://muse-songs.r2.cloudflarestorage.com/songs/..."
            }],
            "playCount": 42,
            "createdAt": "2024-03-20T12:00:00.000Z",
            "updatedAt": "2024-03-20T12:00:00.000Z"
        }],
        "favoriteSongs": [{
            "_id": "65fb1234c8e123456789abcd",
            "title": "Never Gonna Give You Up",
            "duration": 213,
            "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
            "stream_url": "https://muse-songs.r2.cloudflarestorage.com/songs/...",
            "uploader": "Rick Astley",
            "listeningTime": 1800
        }]
    }

Error Responses

Status Code Description Example
400 Bad Request - Invalid input parameters {"error": "Email and password are required."}
401 Unauthorized - Missing or invalid authentication token {"error": "Invalid or expired token."}
403 Forbidden - Not permitted to perform the action {"error": "Access denied"}
404 Not Found - Resource doesn't exist {"error": "Song not found"}
500 Internal Server Error - Server-side error occurred {"error": "Failed to connect to database"}