Web API User Guide
Our Web API provides client applications with top-of-the-line audio and music analysis.
Note that by using DoReMIR developer tools, you accept our Developer Terms of Use.
About the Web API
Through the Doremir Web API your applications can use Doremir functionality. The Doremir Web API is functional in the sense that all requests have some input; Audio, MIDI, etc and all responses have some output; Audio, MIDI, MusicXML, etc. No data is saved for later retrieval.
The Web API endpoints accept input like Audio, MID and MusicXML and return output as for example Audio, MIDI, MusicXML, JSON or plain text.
The analysis API functions are all built around a schema where you first send a start request, which initiates the analysis. Secondly the audio data is sent in chunks using one or more upload request. Finally a result request is sent to get the result of the analysis.
There are multiple reasons for using this three step schema:
- The Doremir Web API is developed to support web clients built with HTML5/CSS/JS. Such clients don’t have the same possibilities to “stream” audio using HTTP chunked transfer encoding as native clients have. Using multiple upload requests enables “streaming” from web clients.
- The analysis may take a long time depending on input. Also at high server loads analysis requests may be queued. Keeping a connection open while waiting for the result is susceptible for timeouts.
Note that by using Doremir developer tools, you accept our Developer Terms of Use.
Access
To use the Web API a Client Token is required. At the moment tokens are created manually. You can request a token by emailing api@doremir.com.
The base address of the API is https://api.doremir.com. There are several endpoints at that address, each with its own unique path. Some endpoints are free of use and others need a subscription. To sign up for a subscription, contact Doremir API services.
Requests
API calls are sent using standard HTTPS POST requests in UTF-8 format to an API endpoint. The input (Audio, MIDI, etc) is passed in the request body. Additional data is passed URL parameters.
Responses
The response data (Audio, MIDI, MusicXML, etc) is received in the response body.
Response Status Codes
The API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:
| Status Code | Description |
|---|---|
| 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; see Error Details. |
| 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. This error can be due to a temporary or permanent condition. |
| 500 | Internal 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 by sending an email to api@doremir.com. |
| 502 | Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server. |
| 503 | Service 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. |
Authentication
Some requests to the Web API require authentication. This is achieved by sending a valid OAuth access token as a request parameter, see the API Endpoint Reference.