Last update: 2021-02-05

Based on simple REST principles, the Musimap Web API endpoints return JSON metadata about music artists, albums and tracks, directly from the provided catalogue.

The base address of our Web API is The API provides a set of endpointsm each with its own unique path. To access data through the Web API, an application must be configured. Authorization is via the Musimap Authentication Stack.

A full documentation is available here. This is described under the openAPI format and you could retrieve the full JSON by running the following command:

curl --location --request OPTIONS '' 


The Musimap Web API is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, Musimap Web API uses appropriate HTTP vers for each action:

GETRetrieves resources
POSTCreates resources
PATCHUpdates resources
DELETEDeletes resoruces

Rate Limiting

Rate Limiting enables Web API to share access bandwidth to its resources equally across all clients.

Rate limiting is applied as per application based on Client ID, and regardless of the number of users who use the application simultaneously.

Note: If Musimap Web API returns status code 429, it means that you have sent too many requests. When this happens, check the Retry-After header, where you will see a number displayed. This is the number of seconds that you need to wait, before you try your request again.


Musimap Web API returns all response data as a JSON object. A wrapper is always used such as the following:

    "status": 200,
    "timestamp": 1605612244215,
    "data": [

status will always reflect the response:

timestamp (in ms) defines when the query has been performed.

data contains the results related to your query.

Note: Depending on your query, other fields could be added such as size, offset, total_size,...

Error Response Schema

Unsuccessful responses return a JSON object containing the following information:

KeyValue TypeDescription
statusintegerThe HTTP status code that is also returned in the response header.
timestampintegerThe timestamp, in ms.
errorstringThe cause of the error.
messagestringA short description of the cause of the error.
    "status": 404,
    "timestamp": 1605613492829,
    "error": "Not Found",
    "message": "Organization Not Found"

Response Status Codes

Web API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:

200OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
201Created - The request has been fulfilled and resulted in a new resource being created.
204No Content - The request has succeeded but returns no message body.
400Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information.
401Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.
404Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.
429Too Many Requests - Rate limiting has been applied.
500Internal Server Error. You should never receive this error because our clever coders catch them all... but if you are unlucky enough to get one, please report it to us.
502Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503Service Unavailable - The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.


All requests to Web API require authentication. This is achieved by sending a valid OAuth access token in the request header:

curl --location --request GET '{YOUR_ENDPOINT}' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'