Singularity API

Base URL: http://localhost:3000/api

All endpoints return JSON with the structure: { success: boolean, data: T }

Songs

GET /api/songs Get songs by IDs or link

Query Param	Type	Required	Description
ids	string	No*	Comma-separated list of song IDs (e.g. `3IoDK8qI,4IoDK8qI`)
link	string (url)	No*	Direct JioSaavn song link (e.g. `https://www.jiosaavn.com/song/houdini/OgwhbhtDRwM`)

* Either ids or link must be provided.

Response: { success: boolean, data: Song[] }

GET /api/songs/{id} Get song by ID

Path Param	Type	Required	Description
id	string	Yes	ID of the song (e.g. `3IoDK8qI`)

Response: { success: boolean, data: Song[] }

GET /api/songs/{id}/suggestions Get song suggestions

Query Param	Type	Required	Default	Description
limit	number	No	`10`	Number of suggestions to retrieve

Response: { success: boolean, data: Song[] }

Albums

GET /api/albums Get album by ID or link

Query Param	Type	Required	Description
id	string	No*	Album ID (e.g. `23241654`)
link	string (url)	No*	Direct JioSaavn album link (e.g. `https://www.jiosaavn.com/album/future-nostalgia/ITIyo-GDr7A_`)

* Either id or link must be provided.

Response: { success: boolean, data: Album }

Artists

GET /api/artists Get artist by ID or link

Query Param	Type	Required	Default	Description
id	string	No*	—	Artist ID (e.g. `1274170`)
link	string (url)	No*	—	Direct JioSaavn artist link
page	number	No	`0`	Page number
songCount	number	No	`10`	Number of songs to fetch
albumCount	number	No	`10`	Number of albums to fetch
sortBy	enum	No	`popularity`	`popularity`, `latest`, `alphabetical`
sortOrder	enum	No	`desc`	`asc`, `desc`

* Either id or link must be provided.

Response: { success: boolean, data: Artist }

GET /api/artists/{id} Get artist by ID

Path/Query Param	Type	Required	Default	Description
id	string	Yes	—	Artist ID (e.g. `1274170`)
page	number	No	`0`	Page number
songCount	number	No	`10`	Number of songs to retrieve
albumCount	number	No	`10`	Number of albums to retrieve
sortBy	enum	No	`popularity`	`popularity`, `latest`, `alphabetical`
sortOrder	enum	No	`desc`	`asc`, `desc`

Response: { success: boolean, data: Artist }

GET /api/artists/{id}/songs Get artist songs

Path/Query Param	Type	Required	Default	Description
id	string	Yes	—	Artist ID (e.g. `1274170`)
page	number	No	`0`	Page number
sortBy	enum	No	`popularity`	`popularity`, `latest`, `alphabetical`
sortOrder	enum	No	`desc`	`asc`, `desc`

Response: { success: boolean, data: ArtistSong[] }

GET /api/artists/{id}/albums Get artist albums

Path/Query Param	Type	Required	Default	Description
id	string	Yes	—	Artist ID (e.g. `1274170`)
page	number	No	`0`	Page number
sortBy	enum	No	`popularity`	`popularity`, `latest`, `alphabetical`
sortOrder	enum	No	`desc`	`asc`, `desc`

Response: { success: boolean, data: ArtistAlbum[] }

Search

All search endpoints require a query parameter.

GET /api/search Global search

Query Param	Type	Required	Description
query	string	Yes	Search query (e.g. `Imagine Dragons`)

Response: { success: boolean, data: { songs, albums, artists, playlists } }

GET /api/search/songs Search songs

Query Param	Type	Required	Default	Description
query	string	Yes	—	Search query (e.g. `Believer`)
page	number	No	`0`	Page number
limit	number	No	`10`	Results per page

Response: { success: boolean, data: SearchSong[] }

GET /api/search/albums Search albums

Query Param	Type	Required	Default	Description
query	string	Yes	—	Search query (e.g. `Evolve`)
page	number	No	`0`	Page number
limit	number	No	`10`	Results per page

Response: { success: boolean, data: SearchAlbum[] }

GET /api/search/artists Search artists

Query Param	Type	Required	Default	Description
query	string	Yes	—	Search query (e.g. `Adele`)
page	number	No	`0`	Page number
limit	number	No	`10`	Results per page

Response: { success: boolean, data: SearchArtist[] }

GET /api/search/playlists Search playlists

Query Param	Type	Required	Default	Description
query	string	Yes	—	Search query (e.g. `Indie`)
page	number	No	`0`	Page number
limit	number	No	`10`	Results per page

Response: { success: boolean, data: SearchPlaylist[] }

Playlists

GET /api/playlists Get playlist by ID or link

Query Param	Type	Required	Default	Description
id	string	No*	—	Playlist ID (e.g. `82914609`)
link	string (url)	No*	—	Direct JioSaavn playlist link
page	number	No	`0`	Page number
limit	number	No	`10`	Songs per page

* Either id or link must be provided.

Response: { success: boolean, data: Playlist }

Error Response

All endpoints may return error responses:

{
  "success": false,
  "message": "error description"
}

400 Bad request — missing or invalid parameters

404 Resource not found

500 Internal server error