Documentation Powered by ReDoc

Oud API Documentation (1.0.1)

Download OpenAPI specification:Download

License: Apache 2.0

Web API endpoints enable application to access the Oud catalog and user data. The endpoints are arranged in a structure defined by an object model.

Authentication

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Artists

Endpoints for artists

Get an Artist

Authorizations:
bearerAuth
path Parameters
artistId
required
string

The ID for the artist.

Responses

200

the response body contains an artist object in JSON format.

400

Invalid ID

404

Not Found - The requested resource could not be found.

get /artists/{artistId}
/artists/{artistId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "genres":
    [
    ],
  • "images":
    [
    ],
  • "displayName": "string",
  • "bio": "string",
  • "popularSongs":
    [
    ],
  • "type": "string"
}

Gets artists of a specific genre

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the genre.

Responses

200

the response body contains a list of artist objects in JSON format.

400

Invalid ID

404

Not Found - The requested resource could not be found.

get /artists/genres/{id}
/artists/genres/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get an Artist's Albums

Authorizations:
bearerAuth
path Parameters
artistId
required
string

The ID for the artist.

query Parameters
limit
integer
Default: 20

The number of album objects to return. Minimum: 1. Maximum: 50. For example: limit=2

offset
integer
Default: 0

The index of the first album to return. (0 is the first album). Use with limit to get the next set of albums.

included_groups
string

A comma-separated list of keywords that will be used to filter the response. If not supplied, all album types will be returned. Valid values are:

  • album
  • single
  • appears_on
  • compilation' For example: include_groups=album,single.

Responses

200

The response body contains an array of simplified album objects (wrapped in a paging object) in JSON format.

400

Invalid ID

404

Not Found - The requested resource could not be found.

get /artists/{artistId}/albums
/artists/{artistId}/albums

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Get an Artist's Top Tracks

Get information about an artist’s top tracks by views.

Authorizations:
bearerAuth
path Parameters
artistId
required
string

The ID for the artist.

Responses

200

the response body contains an object whose key is "tracks" and whose value is an array of up to 10 track objects in JSON format.

400

Invalid ID

404

Not Found - The requested resource could not be found.

get /artists/{artistId}/top-tracks
/artists/{artistId}/top-tracks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tracks":
    [
    ]
}

Get an Artist's Related Artists

Get information about artists similar to a given artist. Similarity is based on genre.

Authorizations:
bearerAuth
path Parameters
artistId
required
string

The ID for the artist.

Responses

200

the response body contains an object whose key is "artists" and whose value is an array of up to 20 artist objects in JSON format.

400

Invalid ID

404

Not Found - The requested resource could not be found.

get /artists/{artistId}/related-artists
/artists/{artistId}/related-artists

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "artists":
    [
    ]
}

Get Several Artists

Get information for several artists based on their IDs.

query Parameters
artistId
required
string

A comma-separated list of IDs for the artists. Maximum: 50 IDs.

Responses

200

the response body contains an object whose key is "artists" and whose value is an array of artist objects in JSON format. Objects are returned in the order requested. If an object is not found, a null value is returned in the appropriate position. Duplicate ids in the query will result in duplicate objects in the response.

400

Invalid ID

get /artists
/artists

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "artists":
    [
    ]
}

Get some Artists

Get information for some artists without specifing anything about them.

Responses

200

the response body contains an array of artist objects in JSON format.

get /artists/some
/artists/some

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Request to be an Artist

User/Guest requests to be an Artist if it's accepted they will be able to upload albums/tracks.

Request Body schema: application/json

JSON object contains the needed information for the request.

genres
required
Array of strings

A list of the genre ID's of the genres of the artist.

name
required
string

The name of the artist.

displayName
required
string

The name that will be displayed on his/her profile

bio
string

a biography or short biographical profile of the artist.

email
required
string

An email for contact

country
required
string

The country of the artist

Responses

200

successful operation

400

The request could not be understood by the server due to malformed syntax.

post /artists/requests
/artists/requests

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "genres":
    [
    ],
  • "name": "string",
  • "displayName": "string",
  • "bio": "string",
  • "email": "string",
  • "country": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string"
}

Uploads an official document image

Uploads an official document that is attached to the request to be an artist.

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of the request

Request Body schema: multipart/form-data
image
string <binary>

Responses

204

the resources are created and the response body is empty.

400

the server cannot or will not process the request due to something that is perceived to be a client error. and the artist request will be discarded and removed from the server and the user should resubmit.

404

Not Found - The requested resource could not be found.

post /artists/requests/{id}/attachments
/artists/requests/{id}/attachments

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Responds to artist requests by accepting or refusing

Determine whether a request to be an artist should by accepted or refused and create an artist if accepted then send informing emails for the applicant.

path Parameters
id
required
string
Request Body schema: application/json
accept
required
boolean

true for accepting and false for refusing the request

Responses

204

successful operation and response body is empty

400

The request could not be understood by the server due to malformed syntax.

post /artists/requests/{id}/handle
/artists/requests/{id}/handle

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "accept": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Update artist's bio

Updates artist's bio

Authorizations:
bearerAuth
Request Body schema: application/json
bio
string

The bio of the artist

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

patch /me/artists/bio
/me/artists/bio

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "bio": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "genres":
    [
    ],
  • "images":
    [
    ],
  • "displayName": "string",
  • "bio": "string",
  • "popularSongs":
    [
    ],
  • "type": "string"
}

Update popular songs

Updates the current artist's list of popular songs

Authorizations:
bearerAuth
Request Body schema: application/json
tracks
required
Array of strings

ID's of the tracks sorted. (maximum 10 tracks)

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

patch /me/artists/top-tracks
/me/artists/top-tracks

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tracks":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "genres":
    [
    ],
  • "images":
    [
    ],
  • "displayName": "string",
  • "bio": "string",
  • "popularSongs":
    [
    ],
  • "type": "string"
}

Follow

Endpoints for managing the artists, users, and playlists that a user follows.

Check if Current User Follows Artists or Users

Check to see if the current user is following one or more artists or other users.

Authorizations:
bearerAuth
query Parameters
type
required
string

The ID type: either artist or user.

ids
required
string

A comma-separated list of the artist or the user IDs to check. For example: ids=74ASZWbe4lXaubB36ztrGX,08td7MxkoHQkXnWAYD8d6Q. A maximum of 50 IDs can be sent in one request.

Responses

200

the response body contains a JSON array of true or false values, in the same order in which the ids were specified.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

get /me/following/contains
/me/following/contains

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • true
]

Check if Users Follow a Playlist

Check to see if one or more users are following a specified playlist.

Authorizations:
bearerAuth
path Parameters
playlistId
required
string

The ID of the playlist.

query Parameters
ids
required
string

A comma-separated list of User IDs; the ids of the users that you want to check to see if they follow the playlist. Maximum: 5 ids.

Responses

200

the response body contains a JSON array of true or false values, in the same order in which the ids were specified.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

get /playlists/{playlistId}/followers/contains
/playlists/{playlistId}/followers/contains

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • true
]

Get a User's Followed Artists or Users

Get a user’s followed artists/users.

Authorizations:
bearerAuth
path Parameters
userId
required
string

The user id requested to view his followings

query Parameters
type
required
string

The ID type: artist or user

limit
integer
Default: 20

The maximum number of items to return. Minimum: 1. Maximum: 50.

offset
integer

The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of followings.

Responses

200

the response body contains an artists object or user object wrapped in paging object.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

get /users/{userId}/following
/users/{userId}/following

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Get a User's Followers

Get a user’s followers

Authorizations:
bearerAuth
path Parameters
userId
required
string

The user id requested to view his followers

query Parameters
limit
integer
Default: 20

The maximum number of items to return. Minimum: 1. Maximum: 50.

offset
integer

The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of followers.

Responses

200

the response body contains a user object wrapped in paging object.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

get /users/{userId}/followers
/users/{userId}/followers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Get Current User's Followers

Get Current User’s followers

Authorizations:
bearerAuth
query Parameters
limit
integer
Default: 20

The maximum number of items to return. Minimum: 1. Maximum: 50.

offset
integer

The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of followers.

Responses

200

the response body contains a user object wrapped in paging object.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

get /me/followers
/me/followers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Follow Artists or Users

Add the current user as a follower of one or more artists or other users.

Authorizations:
bearerAuth
query Parameters
type
required
string

The ID type: either artist or user.

ids
Array of strings

A comma-separated list of the artist or the user IDs. For example: ids=74ASZWbe4lXaubB36ztrGX,08td7MxkoHQkXnWAYD8d6Q. A maximum of 50 IDs can be sent in one request.

Request Body schema: application/json

A JSON array of the artist or user IDs. For example: {ids:["74ASZWbe4lXaubB36ztrGX", "08td7MxkoHQkXnWAYD8d6Q"]}. A maximum of 50 IDs can be sent in one request. Note: if the ids parameter is present in the query string, any IDs listed here in the body will be ignored.

ids
Array of strings

Responses

204

the resources are created and the response body is empty.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

put /me/following
/me/following

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ids":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Get User's Followed Artists or Users

Get the current user’s followed artists/users.

Authorizations:
bearerAuth
query Parameters
type
required
string

The ID type: artist or user

limit
integer
Default: 20

The maximum number of items to return. Minimum: 1. Maximum: 50.

offset
integer

The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of followings.

Responses

200

the response body contains an artists object or user object wrapped in paging object.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

get /me/following
/me/following

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Unfollow Artists or Users

Remove the current user as a follower of one or more artists or other users.

Authorizations:
bearerAuth
query Parameters
type
required
Array of strings

The ID type: artist or user

ids
string

A comma-separated list of the artist or the user IDs. For example: ids=74ASZWbe4lXaubB36ztrGX,08td7MxkoHQkXnWAYD8d6Q. A maximum of 50 IDs can be sent in one request.

Responses

204

The resources are deleted and the response body is empty.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

delete /me/following
/me/following

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Follow a Playlist

Add the current user as a follower of a playlist.

Authorizations:
bearerAuth
path Parameters
playlistId
required
string

The ID of the playlist. Any playlist can be followed, regardless of its public/private status, as long as you know its playlist ID.

Request Body schema: application/json

If true the playlist will be included in user’s public playlists, if false it will remain private.

public
boolean
Default: true

Responses

204

the resources are created and the response body is empty.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

put /playlists/{playlistId}/followers
/playlists/{playlistId}/followers

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "public": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Unfollow a Playlist

Remove the current user as a follower of a playlist.

Authorizations:
bearerAuth
path Parameters
playlistId
required
string

The ID of the playlist that is to be no longer followed.

Responses

204

the resources are deleted and the response body is empty.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

delete /playlists/{playlistId}/followers
/playlists/{playlistId}/followers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Users Profile

Endpoints for user’s profile.

Get Current User's Profile

Get detailed profile information about the current user (including the current user’s username).

Authorizations:
bearerAuth

Responses

200

the response body contains a user object in JSON format.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

get /me
/me

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "5a2539b41c574006c46f1a07",
  • "username": "string",
  • "birthDate": "2020-06-10",
  • "privateSession": false,
  • "gender": "F",
  • "email": "example@example.com",
  • "displayName": "string",
  • "role": "free",
  • "country": "EG",
  • "credit": 0,
  • "plan": null,
  • "images":
    [
    ],
  • "verified": false,
  • "lastLogin": "2020-06-10",
  • "facebook_id": "string",
  • "google_id": "string",
  • "type": "string"
}

Update user's profile image

Updates the current user image

Authorizations:
bearerAuth
Request Body schema: multipart/mixed
images
string <binary>

Responses

200

the response body contains a user object in JSON format.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

patch /me/profilePicture
/me/profilePicture

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "5a2539b41c574006c46f1a07",
  • "username": "string",
  • "birthDate": "2020-06-10",
  • "privateSession": false,
  • "gender": "F",
  • "email": "example@example.com",
  • "displayName": "string",
  • "role": "free",
  • "country": "EG",
  • "credit": 0,
  • "plan": null,
  • "images":
    [
    ],
  • "verified": false,
  • "lastLogin": "2020-06-10",
  • "facebook_id": "string",
  • "google_id": "string",
  • "type": "string"
}

Edit user's profile

Authorizations:
bearerAuth
Request Body schema: application/json

Profile data

email
required
string <email>
passwordConfirm
required
string >= 8 characters
gender
required
string
Enum: "M" "F"
dateOfBirth
required
string <date>

The user`s birthdate, must be at least 10 years old

country
string <ISO ALPHA 2> 2 characters
displayName
required
string

Responses

200

the response body contains a user object in JSON format.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

put /me/profile
/me/profile

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "user@example.com",
  • "passwordConfirm": "stringst",
  • "gender": "M",
  • "dateOfBirth": "2020-06-10",
  • "country": "st",
  • "displayName": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "5a2539b41c574006c46f1a07",
  • "username": "string",
  • "birthDate": "2020-06-10",
  • "privateSession": false,
  • "gender": "F",
  • "email": "example@example.com",
  • "displayName": "string",
  • "role": "free",
  • "country": "EG",
  • "credit": 0,
  • "plan": null,
  • "images":
    [
    ],
  • "verified": false,
  • "lastLogin": "2020-06-10",
  • "facebook_id": "string",
  • "google_id": "string",
  • "type": "string"
}

Start or End a Private Session

Authorizations:
bearerAuth
Request Body schema: application/json

The Value of Private Session to be set

privateSession
required
boolean

Responses

200

the response body contains a user object in JSON format after changing the value of privateSession.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

put /me/privateSession
/me/privateSession

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "privateSession": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "5a2539b41c574006c46f1a07",
  • "username": "string",
  • "birthDate": "2020-06-10",
  • "privateSession": false,
  • "gender": "F",
  • "email": "example@example.com",
  • "displayName": "string",
  • "role": "free",
  • "country": "EG",
  • "credit": 0,
  • "plan": null,
  • "images":
    [
    ],
  • "verified": false,
  • "lastLogin": "2020-06-10",
  • "facebook_id": "string",
  • "google_id": "string",
  • "type": "string"
}

Get a User's Profile

Get public profile information about a user.

Authorizations:
bearerAuth
path Parameters
userId
required
string

Responses

200

the response body contains a user object in JSON format.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

get /users/{userId}
/users/{userId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "5a2539b41c574006c46f1a07",
  • "displayName": "string",
  • "images":
    [
    ],
  • "verified": false,
  • "lastLogin": "2020-06-10",
  • "type": "string"
}

update user password

update user password

Authorizations:
bearerAuth
Request Body schema: application/json

User password and passwordConfirm

currentPassword
required
string <password> >= 8 characters

REQUIRED - The user’s current password

password
required
string <password> >= 8 characters

REQUIRED - The user’s new password

passwordConfirm
required
string <password> >= 8 characters

REQUIRED - The user’s new password confirm

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

patch /me/updatePassword
/me/updatePassword

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "currentPassword": "pa$$word",
  • "password": "pa$$word",
  • "passwordConfirm": "pa$$word"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Albums

Endpoints for albums

add comments for the album

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

id of album to add comment to

Request Body schema: application/json
comment
string

Responses

201

comment added

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

post /albums/{id}/comments
/albums/{id}/comments

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "comment": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

get comments for the album

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

id of album to add comment to

Responses

200

comments on the album

400

bad request

get /albums/{id}/comments
/albums/{id}/comments

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "comments":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Return a single album

Returns information about the album with the given ID

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of album to return

Responses

200

successful operation

400

Invalid ID

get /albums/{id}
/albums/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "album_type": "string",
  • "artists":
    [
    ],
  • "genres":
    [
    ],
  • "image": "string",
  • "name": "string",
  • "release_date": "2020-06-10",
  • "tracks":
    {
    },
  • "type": "string",
  • "released": true
}

Remove an album

Deletes the album with the given ID

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of album to delete

Responses

200

successful operation

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

delete /me/artists/albums/{id}
/me/artists/albums/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "album_type": "string",
  • "artists":
    [
    ],
  • "genres":
    [
    ],
  • "image": "string",
  • "name": "string",
  • "release_date": "2020-06-10",
  • "tracks":
    {
    },
  • "type": "string",
  • "released": true
}

Update an album

Updates the album with the given ID

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of album to update

Request Body schema: application/json
name
string

The name of the album

artists
Array of strings

The ID's of the artists of the album.

genres
Array of strings

A list of the genre ID's of the genres used to classify the album.

album_type
string

the type of the album: one of the following 'single', 'album' or 'compilation'

release_date
string

The date the album was first released

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

patch /me/artists/albums/{id}
/me/artists/albums/{id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "artists":
    [
    ],
  • "genres":
    [
    ],
  • "album_type": "string",
  • "release_date": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "album_type": "string",
  • "artists":
    [
    ],
  • "genres":
    [
    ],
  • "image": "string",
  • "name": "string",
  • "release_date": "2020-06-10",
  • "tracks":
    {
    },
  • "type": "string",
  • "released": true
}

Get several albums

Retrieves the information of the albums specified by given ID's

Authorizations:
bearerAuth
query Parameters
ids
required
string <string>

list of ID's of albums to be retrieved (comma separated)

Responses

200

successful operation

400

Invalid ID

get /albums
/albums

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "albums":
    [
    ]
}

Return the tracks of an album

Retrieves the tracks of the album with the given ID

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of the album containing the tracks

query Parameters
limit
integer

The maximum number of items to return

offset
integer

The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of tracks.

Responses

200

successful operation

400

Invalid ID

404

Not Found - The requested resource could not be found.

get /albums/{id}/tracks
/albums/{id}/tracks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Create a new album

Creates a new album for an artist

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

The name of the album

artists
required
Array of strings

The ID's of the artists of the album.

genres
required
Array of strings

A list of the genre ID's of the genres used to classify the album.

album_type
required
string

the type of the album: one of the following 'single', 'album' or 'compilation'

release_date
required
string

The date the album was first released

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

post /me/artists/albums
/me/artists/albums

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "artists":
    [
    ],
  • "genres":
    [
    ],
  • "album_type": "string",
  • "release_date": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "album_type": "string",
  • "artists":
    [
    ],
  • "genres":
    [
    ],
  • "image": "string",
  • "name": "string",
  • "release_date": "2020-06-10",
  • "tracks":
    {
    },
  • "type": "string",
  • "released": true
}

Update the image of an album

Updates the image of the album with the given ID

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of album to update

Request Body schema: multipart/form-data
image
string <binary>

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

post /me/artists/albums/{id}/images
/me/artists/albums/{id}/images

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "artists":
    [
    ],
  • "albumId": "string",
  • "album":
    {
    },
  • "type": "string",
  • "duartion": 0,
  • "views": 0
}

Release an album

Releases an album and make it public

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of album to release

Request Body schema: application/json
released
required
boolean

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

patch /me/artists/albums/{id}/release
/me/artists/albums/{id}/release

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "released": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "album_type": "string",
  • "artists":
    [
    ],
  • "genres":
    [
    ],
  • "image": "string",
  • "name": "string",
  • "release_date": "2020-06-10",
  • "tracks":
    {
    },
  • "type": "string",
  • "released": true
}

Add a track to an album

Adds a new track to an album for an artist

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of the album, if not given then the track will be single

Request Body schema: application/json
name
required
string

name of the track

artists
required
Array of strings

The ID's of the track's artists

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

post /me/artists/albums/{id}/tracks
/me/artists/albums/{id}/tracks

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "artists":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "album_type": "string",
  • "artists":
    [
    ],
  • "genres":
    [
    ],
  • "image": "string",
  • "name": "string",
  • "release_date": "2020-06-10",
  • "tracks":
    {
    },
  • "type": "string",
  • "released": true
}

Tracks

Endpoints for tracks

Download a track

Download Track with the given id

Authorizations:
bearerAuth (premiumartist)
path Parameters
id
required
string <string>

ID of track to return

Responses

200

No Content - The request has succeeded but returns no message body.

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

get /tracks/{id}/download
/tracks/{id}/download

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Return a single track

Retrieves information about the track with the given ID

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of track to return

Responses

200

successful operation

400

Invalid ID

404

Not Found - The requested resource could not be found.

get /tracks/{id}
/tracks/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "artists":
    [
    ],
  • "albumId": "string",
  • "album":
    {
    },
  • "type": "string",
  • "duartion": 0,
  • "views": 0
}

Remove a track

Deletes the track with the given ID

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of track to delete

Responses

200

successful operation

400

Invalid ID

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

delete /tracks/{id}
/tracks/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "artists":
    [
    ],
  • "albumId": "string",
  • "album":
    {
    },
  • "type": "string",
  • "duartion": 0,
  • "views": 0
}

Update a Track

Updates the track with the given ID

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of track to update

Request Body schema: application/json
name
string

The name of the track

artists
Array of strings

The ID's of the artists of the album.

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

patch /tracks/{id}
/tracks/{id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "artists":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "artists":
    [
    ],
  • "albumId": "string",
  • "album":
    {
    },
  • "type": "string",
  • "duartion": 0,
  • "views": 0
}

Upload Track's file

Uploads the file of the track

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

ID of the track

Request Body schema: multipart/form-data
track
string <binary>

Responses

200

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

post /tracks/{id}
/tracks/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "artists":
    [
    ],
  • "albumId": "string",
  • "album":
    {
    },
  • "type": "string",
  • "duartion": 0,
  • "views": 0
}

Get several tracks

Retrieves information of the tracks specified by given ID's

Authorizations:
bearerAuth
query Parameters
ids
string <string>

list of ID's of tracks to be retrieved (comma separated)

Responses

200

successful operation

400

Invalid ID

get /tracks
/tracks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tracks":
    [
    ]
}

Playlists

Endpoints for Playlists.

add comments for the playlist

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

id of playlist to add comment to

Request Body schema: application/json
comment
string

Responses

201

comment added

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

post /playlists/{id}/comments
/playlists/{id}/comments

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "comment": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

get comments for the playlist

Authorizations:
bearerAuth
path Parameters
id
required
string <string>

id of playlist to add comment to

Responses

200

comments on the playlist

400

bad request

get /playlists/{id}/comments
/playlists/{id}/comments

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "comments":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Get Playlist of specific Id

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the Playlist

Responses

200

the response body contains Playlist object in JSON format.

400

Invalid ID

401

Unauthorized.

403

The specified resource was not found.

404

The specified resource was not found.

get /playlists/{playlist_id}
/playlists/{playlist_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "owner": "string",
  • "tracks":
    [
    ],
  • "collaborative": true,
  • "description": "string",
  • "public": true,
  • "image": "string",
  • "type": "string"
}

change playlist details

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the Playlist

Request Body schema: application/json

tracks to be added

name
string

the new name for the playlist

public
boolean

If true the playlist will be public, if false it will be private. index.

collaborative
boolean

If true , the playlist will become collaborative and other users will be able to modify the playlist in their client.

description
string

Value for playlist description as displayed in Clients and in the Web API.

image/png
string <binary>

the image of the playlist

Responses

200

Update completed

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

put /playlists/{playlist_id}
/playlists/{playlist_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "public": true,
  • "collaborative": true,
  • "description": "string",
  • "image/png": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "owner": "string",
  • "tracks":
    [
    ],
  • "collaborative": true,
  • "description": "string",
  • "public": true,
  • "image": "string",
  • "type": "string"
}

Remove a Playlist's Tracks

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the Playlist

query Parameters
Tracks
object

Tracks to be removed from playlist and should be sent in body api doesnot support that

Responses

204

Tracks removed successfully and the response body is empty

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

delete /playlists/{playlist_id}/tracks
/playlists/{playlist_id}/tracks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Get a Playlist's Tracks

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the Playlist

query Parameters
limit
integer [ 1 .. 100 ]
Default: 100

The maximum number of tracks to return.

offset
integer
Default: 0

The index of the first track to return.

Responses

200

the response body contains array of album objects in JSON format.

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

get /playlists/{playlist_id}/tracks
/playlists/{playlist_id}/tracks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Add tracks to a specific playlist

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the Playlist

query Parameters
position
integer

The position to insert the tracks, a zero-based index.

Request Body schema: application/json
ids
Array of strings

Responses

204

tracks has been added and the response body is empty

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

post /playlists/{playlist_id}/tracks
/playlists/{playlist_id}/tracks

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ids":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

ReOrder Playlists Tracks

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the Playlist

Request Body schema: application/json

info about Reorder a Playlist's Tracks

rangeStart
integer

The position of the first track to be reordered

rangeLength
integer
Default: 1

The amount of tracks to be reordered.The range of tracks to be reordered begins from the range_start position, and includes the range_length subsequent tracks

insertBefore
integer

The position where the tracks should be inserted.To reorder the tracks to the end of the playlist, simply set insert_before to the position after the last track.

Responses

204

tracks has been ReOrdered

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

put /playlists/{playlist_id}/tracks
/playlists/{playlist_id}/tracks

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "rangeStart": 0,
  • "rangeLength": 1,
  • "insertBefore": 0
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Get a List of current User's Playlists

Authorizations:
bearerAuth
query Parameters
isOwner
required
boolean

if true you will get the playlists created by current user if false you will get the playlists followed by current user

limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of playlists to return.

offset
integer <= 100000
Default: 0

The index of the first playlist to return.

Responses

200

list of playlist of the user

400

bad request

401

Unauthorized.

get /me/playlists
/me/playlists

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Get Playlist Cover Image

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the playlist

Responses

200

the cover image of the playlist

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

get /playlists/{playlist_id}/images
/playlists/{playlist_id}/images

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "image": "string"
}

Upload a Custom Playlist Cover Image

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the playlist

Request Body schema: image/png
string <binary>

Responses

202

Accepted but not completed

204

successful and the response body is empty

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

put /playlists/{playlist_id}/images
/playlists/{playlist_id}/images

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Replace a playlist's tracks

Authorizations:
bearerAuth
path Parameters
playlist_id
required
string

Id of the playlist

Request Body schema: application/json

info about Reorder a Playlist's Tracks

ids
Array of strings

uris of the tracks

Responses

204

Replaced track in playlist

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

put /playlists/{playlist_id}/tracks/Replace
/playlists/{playlist_id}/tracks/Replace

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ids":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

create a playlist

Authorizations:
bearerAuth
path Parameters
user_id
required
string

Id of the user creating the playlist

Request Body schema: application/json

info of Playlist

name
string

the new name for the playlist

public
boolean
Default: true

If true the playlist will be public, if false it will be private. index.

collaborative
boolean
Default: false

If true , the playlist will become collaborative and other users will be able to modify the playlist in their client.

description
string

Value for playlist description as displayed in Clients and in the Web API.

image/png
string <binary>

the image of the playlist

Responses

200

playlist created

400

Invalid ID

401

Unauthorized.

post /users/{user_id}/playlists
/users/{user_id}/playlists

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "public": true,
  • "collaborative": false,
  • "description": "string",
  • "image/png": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "owner": "string",
  • "tracks":
    [
    ],
  • "collaborative": true,
  • "description": "string",
  • "public": true,
  • "image": "string",
  • "type": "string"
}

Get a List of a User's Playlists

Authorizations:
bearerAuth
path Parameters
user_id
required
string

Id of the user

query Parameters
limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of playlists to return.

offset
integer <= 100000
Default: 0

The index of the first playlist to return.

Responses

200

list of playlist of the user

400

bad request

401

Unauthorized.

get /users/{user_id}/playlists
/users/{user_id}/playlists

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Library

Endpoints for User Library.

Save Albums for Current User

Authorizations:
bearerAuth
query Parameters
ids
required
Array of strings

comma separated ids of the Albums to be saved

Responses

201

Album Saved

400

Invalid ID

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

put /me/albums
/me/albums

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Remove Saved Albums for Current User

Authorizations:
bearerAuth
query Parameters
ids
required
Array of strings

comma separated ids of the Albums to be deleted

Responses

204

Albums removed successfully and the body of the response is empty

400

bad request

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

delete /me/albums
/me/albums

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Get Current User's Saved Albums

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of albums to return.

offset
integer
Default: 0

The index of the first album to return.

Responses

200

list of playlist of the user

400

bad request

401

Unauthorized.

get /me/albums
/me/albums

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Check User's Saved Albums

Checks if the albums with the given ID's are saved

Authorizations:
bearerAuth
query Parameters
ids
required
Array of strings

A comma-separated list of the IDs for the albums

Responses

200

true or false if found album saved

400

Invalid ID

401

Unauthorized.

get /me/albums/contains
/me/albums/contains

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • true
]

Check User's Saved tracks

Checks if the tracks with the given ID's are saved

Authorizations:
bearerAuth
query Parameters
ids
required
Array of strings

A comma-separated list of the IDs for the tracks

Responses

200

true or false if found track saved

400

Invalid ID

401

Unauthorized.

get /me/tracks/contains
/me/tracks/contains

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • true
]

Save Tracks for Current User

Authorizations:
bearerAuth
query Parameters
ids
required
Array of strings

comma separated Ids of the Tracks to be saved

Responses

200

Tracks Saved

400

Invalid ID

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

put /me/tracks
/me/tracks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Remove Saved Tracks for Current User

Authorizations:
bearerAuth
query Parameters
ids
required
Array of strings

the IDs of the Tracks to be removed

Responses

204

Tracks removed successfully

400

bad request

401

Unauthorized.

403

forbidden

404

The specified resource was not found.

delete /me/tracks
/me/tracks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Get Current User's Saved tracks

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of tracks to return.

offset
integer
Default: 0

The index of the first track to return.

Responses

200

list of playlist of the user

400

bad request

401

Unauthorized.

get /me/tracks
/me/tracks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Search

Endpoints for Searching.

what user recently searched for

store what the user used from rescent search

Request Body schema: application/json
id
string

the id of the used item

type
string

item can be 'track' or 'user' or 'Album' or 'Artist'

Responses

204

successful operation

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

put /me/search/recent
/me/search/recent

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "type": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

retrive what user recently searched for

retrive what the user used from rescent search

query Parameters
limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of items to return.

offset
integer <= 2000
Default: 0

The index of the first item to return.

Responses

200

item the user used in recent search

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

get /me/search/recent
/me/search/recent

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Search for an Item

query Parameters
q
required
string

name of what you want to search for eg q = Top this will return items with name that includes Top.

type
string

A comma-separated list of item types to search across. Valid types are album ,User, Artist, playlist, and track. Search results include hits from all the specified item types.Its optional if not sent search will be on all types.

limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of items to return.

offset
integer <= 2000
Default: 0

The index of the first item to return.

Responses

200

the response body contains array of objects in JSON format with the required type.

400

bad request

get /search
/search

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tracks":
    [
    ],
  • "albums":
    [
    ],
  • "artists":
    [
    ],
  • "users":
    [
    ],
  • "playlists":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Premium

Endpoints for Premium.

Redeeming coupons that gives the user credit (Oud Coins)

Redeeming a valid coupon increases the user's credit (Oud Coins) that can be used for subscribing in the Premium Plan

Authorizations:
bearerAuth
Request Body schema: application/json
couponId
string

The coupon code

Responses

200

the response body contains the user private object with current credit in JSON format.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

patch /me/premium/redeem
/me/premium/redeem

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "couponId": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "5a2539b41c574006c46f1a07",
  • "username": "string",
  • "birthDate": "2020-06-10",
  • "privateSession": false,
  • "gender": "F",
  • "email": "example@example.com",
  • "displayName": "string",
  • "role": "free",
  • "country": "EG",
  • "credit": 0,
  • "plan": null,
  • "images":
    [
    ],
  • "verified": false,
  • "lastLogin": "2020-06-10",
  • "facebook_id": "string",
  • "google_id": "string",
  • "type": "string"
}

Subscribe or Resubscribe an user by spending The User's credit (Oud Coins)

subscribe or resubscribe an user by spending The User's credit (Oud Coins) as a gift. Sends a confirmation email for the gifted user that informs him that he was gifted and his end date.

Authorizations:
bearerAuth
Request Body schema: application/json
userId
string

The Gifted User ID.

Responses

200

the response body contains the user private object with current credit in JSON format.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

patch /me/premium/gift
/me/premium/gift

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "userId": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "5a2539b41c574006c46f1a07",
  • "username": "string",
  • "birthDate": "2020-06-10",
  • "privateSession": false,
  • "gender": "F",
  • "email": "example@example.com",
  • "displayName": "string",
  • "role": "free",
  • "country": "EG",
  • "credit": 0,
  • "plan": null,
  • "images":
    [
    ],
  • "verified": false,
  • "lastLogin": "2020-06-10",
  • "facebook_id": "string",
  • "google_id": "string",
  • "type": "string"
}

Subscribe to Premium plan

Subscribe to Premium plan

Authorizations:
bearerAuth

Responses

200

the response body the user private object with plan updated to be the end date of the premium subscription.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

patch /me/premium/subscribe
/me/premium/subscribe

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "5a2539b41c574006c46f1a07",
  • "username": "string",
  • "birthDate": "2020-06-10",
  • "privateSession": false,
  • "gender": "F",
  • "email": "example@example.com",
  • "displayName": "string",
  • "role": "free",
  • "country": "EG",
  • "credit": 0,
  • "plan": null,
  • "images":
    [
    ],
  • "verified": false,
  • "lastLogin": "2020-06-10",
  • "facebook_id": "string",
  • "google_id": "string",
  • "type": "string"
}

UsersAuth

Endpoints for user authentication

Create new user account

Create new user account

Request Body schema: application/json

Account Data

username
required
string <string> [ 5 .. 30 ] characters

REQUIRED - The user’s username, as entered by the user when creating their account.

birthDate
string <date> Nullable

OPTIONAL - The user`s birthdate, must be at least 10 years old

email
required
string <email>

REQUIRED - The user’s email address, as entered by the user when creating their account.

password
required
string <password> >= 8 characters

REQUIRED - The user’s password

passwordConfirm
required
string <password> >= 8 characters

REQUIRED - The user’s password confirm

displayName
required
string <string>

REQUIRED - User Display Name

role
required
string <string>
Enum: "free" "premium" "artist"

REQUIRED - User System Role

country
required
string <ISO Alpha 2> 2 characters

User Country Name

gender
string
Enum: "F" "M"
github_id
string
google_id
string
facebook_id
string

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

post /users/signup
/users/signup

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "username": "string",
  • "birthDate": "2020-06-10",
  • "email": "example@example.com",
  • "password": "pa$$word",
  • "passwordConfirm": "pa$$word",
  • "displayName": "string",
  • "role": "free",
  • "country": "EG",
  • "gender": "F",
  • "github_id": "string",
  • "google_id": "string",
  • "facebook_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Log in

Log in

Request Body schema: application/json

Login with user’s email and password

email
required
string <email>

REQUIRED - The user’s email address, as entered by the user when creating their account.

password
required
string <password> >= 8 characters

REQUIRED - The user’s password

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

429

Too Many Requests

post /users/login
/users/login

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "example@example.com",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Request two way auth for signup, send email with t

Request two way auth for signup, send email with token to user

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

post /me/verify
/me/verify

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Two way auth for signup - Change verified attribut

Two way auth for signup - Change verified attribute is user account to true

path Parameters
token
required
string >= 8 characters

Authentication token to verify the user account

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

patch /users/verify/{token}
/users/verify/{token}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Forgot user password

Forgot user password

Request Body schema: application/json

User email

email
string <email>

Responses

200

OK - The token sent to email

404

Not Found - The requested resource could not be found.

post /users/forgotPassword
/users/forgotPassword

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "example@example.com"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "200",
  • "message": "Token sent to email!"
}

reset user password

reset user password

path Parameters
token
required
string >= 8 characters

Authentication token to verify the user account

Request Body schema: application/json

User password and passwordConfirm

password
required
string <password> >= 8 characters

REQUIRED - The user’s new password

passwordConfirm
required
string <password> >= 8 characters

REQUIRED - The user’s new password confirm

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

patch /users/resetPassword/{token}
/users/resetPassword/{token}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "password": "pa$$word",
  • "passwordConfirm": "pa$$word"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Auth

Endpoints for general authentication

Authentication with facebook

Authentication with facebook

Request Body schema: application/json

Facebook access token

access_token
string

Facebook access token

Responses

200

Facebook Auth response. send user account and x-auth-token if user is already exists. else send user data to signup

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

post /auth/facebook
/auth/facebook

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "access_token": "string"
}

Response samples

Content type
application/json
Example
UserWithToken
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Connect or disconnect your user account with faceb

Connect or disconnect your user account with facebook.

Request Body schema: application/json

Facebook access token

access_token
string

Facebook access token, if passed connect with facebook else disconnect

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

patch /auth/facebook
/auth/facebook

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "access_token": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Authentication with google

Authentication with google

Request Body schema: application/json

Google access token

access_token
string

Google access token

Responses

200

Google Auth response. send user account and x-auth-token if user is already exists. else send user data to signup

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

post /auth/google
/auth/google

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "access_token": "string"
}

Response samples

Content type
application/json
Example
UserWithToken
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Connect or disconnect your user account with googl

Connect or disconnect your user account with google.

Request Body schema: application/json

Google access token

access_token
string

Google access token, if passed connect with google else disconnect

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

patch /auth/google
/auth/google

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "access_token": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Authentication with github

Authentication with github

Request Body schema: application/json

Github access token

access_token
string

Github access token

Responses

200

Github Auth response. send user account and x-auth-token if user is already exists. else send user data to signup

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

post /auth/github
/auth/github

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "access_token": "string"
}

Response samples

Content type
application/json
Example
UserWithToken
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Connect or disconnect your user account with githu

Connect or disconnect your user account with github.

Request Body schema: application/json

Google access token

access_token
string

Github access token, if passed connect with github else disconnect

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

patch /auth/github
/auth/github

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "access_token": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Refresh access token

Refresh access token

cookie Parameters
refresh_token
string

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

post /auth/refresh_token
/auth/refresh_token

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "user":
    {
    }
}

Remove refresh token from the server

Remove refresh token from the server

cookie Parameters
refresh_token
string

Responses

204

No Content - The request has succeeded but returns no message body.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

post /auth/refresh_token/reject
/auth/refresh_token/reject

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Player

Endpoints for player

Get Information About The User's Current Playback

Get Information About The User's Current Playback

Authorizations:
bearerAuth

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

204

No Content - The request has succeeded but returns no message body.

get /me/player
/me/player

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "device":
    {
    },
  • "progressMs": 0,
  • "isPlaying": true,
  • "shuffleState": true,
  • "repeatState": "off",
  • "currentlyPlayingType": "unknown",
  • "item":
    {
    },
  • "actions":
    {
    },
  • "context":
    {
    }
}

Transfer a User's Playback

Transfer a User's Playback

Authorizations:
bearerAuth
Request Body schema: application/json

DeviceIds and play

deviceIds
required
Array of strings

Required. A JSON array containing the ID of the device on which playback should be started/transferred. For example: {deviceIds:["74ASZWbe4lXaubB36ztrGX"]} Note: Although an array is accepted, only a single deviceId is currently supported. Supplying more than one will return 400 Bad Request

play
boolean

Optional. true: ensure playback happens on new device.false: keep the current playback state.

Responses

204

No Content - The request has succeeded but returns no message body.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

put /me/player
/me/player

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "deviceIds":
    [
    ],
  • "play": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Get the User's Currently Playing Track

Get the User's Currently Playing Track

Authorizations:
bearerAuth

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

204

No Content - The request has succeeded but returns no message body.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

get /me/player/currently-playing
/me/player/currently-playing

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "track":
    {
    },
  • "context":
    {
    }
}

Get Current User's Recently Played Tracks

Get Current User's Recently Played Tracks

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 50 ]
Default: 20

Optional. The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

after
integer <Unix Millisecond>

Optional. A Unix timestamp in milliseconds. Returns all items after (but not including) this cursor position. If after is specified, before must not be specified.

before
integer <Unix Millisecond>

Optional. A Unix timestamp in milliseconds. Returns all items before (but not including) this cursor position. If before is specified, after must not be specified.

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

204

No Content - The request has succeeded but returns no message body.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

get /me/player/recently-played
/me/player/recently-played

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0
}

Get a User's Available Devices

Get a User's Available Devices

Authorizations:
bearerAuth

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

get /me/player/devices
/me/player/devices

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Queue

Endpoints for queue

Delete a track from Queue. If the deleted track wa

Delete a track from Queue. If the deleted track was the playing track the queue will play the first track if found and if not it will play the last queue if found

Authorizations:
bearerAuth
query Parameters
queueIndex
integer [ 0 .. 1 ]
Default: 0

Optional. The index of the queue Default 0 must be greater than 0 if 0 get the current queue if 1 get the last queue

trackIndex
integer >= 0

Optional, the track index to be deleted, must be positive. pass track Index or trackId if nothing passed thow 400 BadRequest if passed both 400 BadRequest

trackId
string <uuid>

Optional, the track id to be deleted, must be positive. pass trackIndex or trackId if nothing passed thow 400 BadRequest if passed both 400 BadRequest

Responses

204

No Content - The request has succeeded but returns no message body.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

delete /me/queue
/me/queue

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Edit Track Position

Edit Track Position

Authorizations:
bearerAuth
query Parameters
queueIndex
integer [ 0 .. 1 ]
Default: 0

Optional. The index of the queue Default 0 must be greater than 0 if 0 get the current queue if 1 get the last queue

trackIndex
integer >= 0

Optional, the track index to be moved, zero based, must be positive. pass trackIndex or trackId if nothing passed 400 BadRequest if passed both 400 BadRequest

trackId
string <uuid>

Optional, the track id to be moved, must be positive. pass trackIndex or trackId if nothing passed thow 400 BadRequest if passed both 400 BadRequest

newIndex
required
integer >= 0

Required, the new track index, zero based, must be positive. if index greater than the queue length 400 BadRequest

Responses

204

No Content - The request has succeeded but returns no message body.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

patch /me/queue
/me/queue

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Add an Item to the User's Playback Current Queue

Add an Item to the User's Playback Current Queue

Authorizations:
bearerAuth
query Parameters
queueIndex
integer [ 0 .. 1 ]
Default: 0

Optional. The index of the queue Default 0 must be greater than 0 if 0 get the current queue if 1 get the last queue

deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

trackId
required
string <uuid>

Track ID to add to queue

Responses

204

No Content - The request has succeeded but returns no message body.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

post /me/queue
/me/queue

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Get User's Playback Queue

Get User's Playback Queue

Authorizations:
bearerAuth
query Parameters
queueIndex
integer [ 0 .. 1 ]
Default: 0

Optional. The index of the queue Default 0 must be greater than 0 if 0 get the current queue if 1 get the last queue

Responses

200

OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.

204

No Content - The request has succeeded but returns no message body.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

get /me/queue
/me/queue

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tracks":
    [
    ],
  • "total": 0
}

Set Volume For User's Playback

Set Volume For User's Playback

Authorizations:
bearerAuth
query Parameters
deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

volumePercent
integer [ 0 .. 100 ]

Required. Integer. The volume to set. Must be a value from 0 to 100 inclusive.

Responses

204

No Content - The request has succeeded but returns no message body.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

put /me/player/volume
/me/player/volume

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Skip User’s Playback To Previous Track. If the rep

Skip User’s Playback To Previous Track. If the repeat state in player is context and the playing track is the first track it will go to the last track in the queue. If the repeat state in player is not context and the playing track is the first track it will play will play the last queue if found.

Authorizations:
bearerAuth
query Parameters
deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Responses

204

No Content - The request has succeeded but returns no message body.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

post /me/player/previous
/me/player/previous

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Skip User’s Playback To Next Track. If the repeat

Skip User’s Playback To Next Track. If the repeat state in player is context and the playing track is the last track it will go to the first track in the queue. If the repeat state in player is not context and the playing track is the last track it will create a new queue similar to the playing queue.

Authorizations:
bearerAuth
query Parameters
deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Responses

204

No Content - The request has succeeded but returns no message body.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

post /me/player/next
/me/player/next

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Pause a User's Playback

Pause a User's Playback

Authorizations:
bearerAuth
query Parameters
deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Responses

204

No Content - The request has succeeded but returns no message body.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

put /me/player/pause
/me/player/pause

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Seek To Position In Currently Playing Track

Seek To Position In Currently Playing Track

Authorizations:
bearerAuth
query Parameters
positionMs
required
integer

Required. The position in milliseconds to seek to. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Responses

204

No Content - The request has succeeded but returns no message body.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

put /me/player/seek
/me/player/seek

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Set Repeat Mode On User’s Playback

Set Repeat Mode On User’s Playback

Authorizations:
bearerAuth
query Parameters
state
required
string
Enum: "track" "context" "off"

Required. track, context or off. track will repeat the current track.context will repeat the current context. off will turn repeat off.

deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Responses

204

No Content - The request has succeeded but returns no message body.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

put /me/player/repeat
/me/player/repeat

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Toggle Shuffle For User’s Playback

Toggle Shuffle For User’s Playback

Authorizations:
bearerAuth
query Parameters
state
required
boolean

Required true : Shuffle user’s playback false : Do not shuffle user’s playback.

deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Responses

204

No Content - The request has succeeded but returns no message body.

403

Forbidden - The server understood the request, but is refusing to fulfill it.

404

Not Found - The requested resource could not be found.

put /me/player/shuffle
/me/player/shuffle

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Start/Resume a User's Playback. if the user is a f

Start/Resume a User's Playback. if the user is a free user every 3 tracks 1 ad will be played

Authorizations:
bearerAuth
query Parameters
deviceId
integer

Optional. The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

queueIndex
integer [ 0 .. 1 ]
Default: 0

Optional. The index of the queue if 0 get the current queue if 1 get the last queue, if not supplied the user’s current queue is the target.

Request Body schema: application/json
contextUri
string <uri>

Optional. Oud URI of the context to play. Valid contexts are album, artist, playlist.

uris
Array of strings <uri>

Optional. A JSON array of the Oud track URIs to play

offset
object

Optional. Indicates from where in the context playback should start. Only available when contextUri corresponds to an album or playlist object, or when the uris parameter is used.position is zero based and can’t be negative. Example: "offset": {"position": 5}. “uri” is a string representing the uri of the item to start at. Example: 'offset': {"uri": "oud:track:1301WleyT98MSxVHPZCA6M"}

positionMs
integer

Optional. Indicates from what position to start playback. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

Responses

204

No Content - The request has succeeded but returns no message body.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

put /me/player/play
/me/player/play

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "contextUri": "oud:album:4iV5W9uYEdYUVa79Axb7Rh",
  • "uris":
    [
    ],
  • "offset": { },
  • "positionMs": 0
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Genres

Endpoints for genres

Get a genre

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID for the genre.

Responses

200

the response body contains a genre object in JSON format.

400

Invalid ID

404

Not Found - The requested resource could not be found.

get /genres/{id}
/genres/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string"
}

Get all genres

Get all genres inside a paging object

query Parameters
limit
integer

maximum number of genres to return (maximum 50, default 50)

offset
integer

number of genres to skip from beginning to return (starts from zero)

Responses

200

list of genres inside a paging object

400

Invalid ID

get /genres
/genres

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Notifications

Endpoints for notifications

Updates the registration token of a user

Updates the registration token that is used to send nofications to the user via Firebase Cloud Messaging(FCM).

Authorizations:
bearerAuth
Request Body schema: application/json
token
string

The registration token of the user

Responses

204

the resources are updated and the response body is empty.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

put /me/notifications/
/me/notifications/

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Chat

Endpoints for Chatting

Get messages' threads

gets the messages' threads of the user in paging object sorted from most frequent modified to least

Authorizations:
bearerAuth
query Parameters
limit
integer

maximum number of threads to return (maximum 50, default 20)

offset
integer

number of threads to skip from beginning to return (starts from zero)

Responses

200

list of threads inside a paging object

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

get /me/chat/
/me/chat/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Get messages of a thread

gets a specific thread of the user with its messages wrapped in paging object sorted from most frequent one to least.

Authorizations:
bearerAuth
path Parameters
id
required
string

ID of the thread

query Parameters
limit
integer

maximum number of messages to return (maximum 50, default 20)

offset
integer

number of messages to skip from beginning to return (starts from zero)

Responses

200

A thread with messages paging object

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

get /me/chat/{id}
/me/chat/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "from":
    {
    },
  • "to":
    {
    },
  • "read": true,
  • "updatedAt": "string",
  • "createdAt": "string",
  • "messages":
    {
    }
}

Send Message to a Thread

sends a message to a specific thread of the user.

Authorizations:
bearerAuth
path Parameters
id
required
string

ID of the recipient

Request Body schema: application/json
message
string

The contents of the message

Responses

201

Created - The request has been fulfilled and resulted in a new resource being created.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

post /me/chat/{id}
/me/chat/{id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "message": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Delete Message From a Thread

Deletes a specific message from a thread

Authorizations:
bearerAuth
path Parameters
id
required
string

ID of the thread

messageId
required
string

ID of the message to be deleted

Responses

204

No Content - The request has succeeded but returns no message body.

400

Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.

401

Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.

404

Not Found - The requested resource could not be found.

delete /me/chat/{id}/{messageId}
/me/chat/{id}/{messageId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string",
  • "message": "string"
}

Browse

Get Category of specific Id

Authorizations:
bearerAuth
path Parameters
categoryId
required
string

Id of the Category

Responses

200

the response body contains category object in JSON format.

400

Invalid ID

401

Unauthorized.

404

The specified resource was not found.

get /browse/categories/{categoryId}
/browse/categories/{categoryId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "_id": "string",
  • "name": "string",
  • "icon": "string"
}

Get Category's Playlists of specific Id

Authorizations:
bearerAuth
path Parameters
category_id
required
string

Id of the Category

query Parameters
limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of items to return.

offset
integer
Default: 0

The index of the first item to return.

Responses

200

the response body contains array of Simplified Playlist objects in JSON format.

400

Invalid ID

401

Unauthorized.

404

The specified resource was not found.

get /browse/categories/{category_id}/playlists
/browse/categories/{category_id}/playlists

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Get List of Categories

query Parameters
offset
integer
Default: 0

The index of the first item to return.

limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of items to return.

Responses

200

the response body contains array of Simplified Playlist objects in JSON format.

400

Invalid ID

404

The specified resource was not found.

get /browse/categories
/browse/categories

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}

Get a List of New Releases

query Parameters
offset
integer
Default: 0

The index of the first item to return.

limit
integer [ 1 .. 50 ]
Default: 20

The maximum number of items to return.

Responses

200

the response body contains array of album objects in JSON format.

400

Invalid ID

404

The specified resource was not found.

get /browse/new-releases
/browse/new-releases

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total": 0
}