API Documentation

API Documentation

The Clyp API is a JSON based RESTful API that powers clyp.it directly via CORS, as well as our mobile apps. Using Clyp's API, you can do everything that's available on clyp.it.

Request API Access

Audio file

POST https://upload.clyp.it/upload

Upload an audio file. Accepted file types are mp3, ogg, m4a, wav, aiff, aif and 3gpp. Regardless of file type when uploading, a resulting mp3 and ogg will be created and made available. The title of the audio file will be set to that of the name of the uploaded file.

Parameters:

  • audioFile - The binaries of the audio file.
  • description - Optional. The description of the audio file. Maximum allowed length is 420 characters.
  • longitude - Optional. The longitude of where the audio file was recorded. If passed in, latitude becomes required. Value must be between -15069 and 15069 degrees.
  • latitude - Optional. The latitude of where the audio file was recorded. If passed in, longitude becomes required. Value must be between -90 and 90 degrees.

Uploads are done via a multipart/form-data POST. Consider the following form:

  • <form action="https://upload.clyp.it/upload" enctype="multipart/form-data" method="post">
  •     <input type="file" name="audioFile">
  •     <input type="submit" value="Send to Clyp">
  • </form>

It will create a request that looks like this:

  • POST https://upload.clyp.it/upload HTTP/1.1
  • Host: upload.clyp.it
  • Connection: keep-alive
  • Content-Type: multipart/form-data; boundary=---------------------------21632794128452
  • Content-Length: 5005
  • -----------------------------21632794128452
  • Content-Disposition: form-data; name="audioFile"; filename="MyAudioFile.mp3"
  • Content-Type: audio/mpeg
  • (Audio file data goes here)

GET https://api.clyp.it/{id}

Gets all relevant metadata of an audio file. This includes location of the mp3 and ogg files, title, description, duration of audio file in seconds, URL of the player page for the given audio file, and latitude/longitude of where the audio file was recorded.

PATCH https://api.clyp.it/{id}

Authenticated owners can update the title and/or description and/or status of their audio file.

Parameters:

  • title - Title of the audio file. Maximum of 250 characters.
  • description - Description of the audio file. Maximum of 420 characters.
  • status - Public, Private, Deleted, DownloadDisabled, PrivateDownloadDisabled

Headers:

Content- Type: application/json

DELETE https://api.clyp.it/{id}

Authenticated owners can delete their audio file.

GET https://api.clyp.it/{id}.mp3

Gets the MP3 encoded audio file. Expect a 302 redirect, even though this might not always be the case. The file will have a sample rate of 44100 Hz and a bit rate of 128 kb/s.

GET https://api.clyp.it/{id}.ogg

Gets the OGG encoded audio file. Expect a 302 redirect, even though this might not always be the case. The file will have a sample rate of 44100 Hz and a bit rate of 112 kb/s.

GET https://api.clyp.it/{id}/soundwave

Gets the sound wave of the audio file, represented by 4,000 equidistant data points. Regardless of the time duration of the audio file, 4,000 data points will always be returned. Each data point is an integer value with a range of 0 - 100, representing the amplitude at that proportionate point in time. For example, consider an audio file that is 42 seconds long. The 2,000th data point returned represents the amplitude of the audio at the 21 second mark.

Browse audio files

GET https://api.clyp.it/categorylist

Gets a list of Clyp's category lists. To retrieve any of the category lists returned by this resource, follow the 'Location' property with a GET. The result of the secondary GET call will return a list of 10 random audio files that have been tagged with a given category.

GET https://api.clyp.it/featuredlist

Gets a list of Clyp's featured lists. To retrieve any of the featured lists returned by this resource, follow the 'Location' property with a GET. More information on some of these featured lists is provided in this section of documentation.

GET https://api.clyp.it/featuredlist/nearby

Get audio files that were uploaded near a given location. For best results, pass in both latitude and longitude as query string parameters. If latitude and longitude are not passed in, we will geocode the requesting IP address and the resulting latitude and longitude will be used.

Parameters:

  • count - Optional. Limits number of results. Valid range of 1 - 100. Default value is 10.
  • longitude - Optional. The longitude to use when searching for nearby audio files. If passed in, latitude becomes required. Value must be between -15069 and 15069 degrees.
  • latitude - Optional. The latitude to use when searching for nearby audio files. If passed in, longitude becomes required. Value must be between -90 and 90 degrees.

GET https://api.clyp.it/featuredlist/popular

Gets the most played audio files over the last 1 day.

Parameters:

count - Optional. Limits number of results. Valid range of 1 - 100. Default value is 10.

GET https://api.clyp.it/featuredlist/random

Gets a random list of audio files.

Parameters:

count - Optional. Limits number of results. Valid range of 1 - 100. Default value is 10.

GET https://api.clyp.it/featuredlist/recent

Gets a random list of audio files.

Parameters:

count - Optional. Limits number of results. Valid range of 1 - 100. Default value is 10.

GET https://api.clyp.it/featuredlist/featured

Gets a random list of audio files.

Parameters:

count - Optional. Limits number of results. Valid range of 1 - 100. Default value is 10.