-
-
Notifications
You must be signed in to change notification settings - Fork 12
API Documentation
The Musical Artifacts API aims to make it possible to integrate the files and metadata collected by the website inside others sites, software and mobile apps which could benefit from the presets, configuration files and sound libraries hosted and catalogued on our server.
The API consists of JSON endpoints for the artifacts which expose the useful data and file urls publicly in an easily consumable format. It also includes support for cookie-less authentication via the JWT standard and the editing and creation of artifacts via POST requests.
Here follows a quick explanation of each of the API functions with HTTP pseudo-code examples and actual API calls using the curl command line application. These can be easily translated to other HTTP libraries or language bindings of your preference.
For implementation examples and ideas see the Musical Artifacts API examples repository and the integrations page.
The application URLS can be requested in json format for consumption by other applications. Some examples:
GET /artifacts.json # listing all artifacts
GET /artifacts.json?q=guitar # artifacts resulting of a search for 'guitar'
If you need help creating a search query, just search for the relevant artifacts in the web UI and copy the URL and use it with artifacts.json instead of artifacts.
# GET /artifacts.json?q=guitar
[
{
name: 'Presets for Stick Quintar / Guitar with low z pickup',
author: 'Broomy',
file_hash: '233134ac1d5b9da250ee31ba984153b...',
file: '/artifacts/116/BroomTreble.gx',
license: 'gpl',
url: 'https://musical-artifacts.com/artifacts/116.json'
},
{
name: 'D-Juntu! Preset - Djent Preset',
author: 'Babis Kouvalis',
file_hash: 'f91c691e94ada2f3c8b94823f0cd0342...',
file: '/artifacts/115/D-Juntu_.gx',
license: 'public',
url: 'https://musical-artifacts.com/artifacts/115.json'
}
]
GET /artifacts/115.json
{
"id": 115,
"name": "D-Juntu! Preset - Djent Preset",
"description": "Here is a preset I made for Djent-ChugChug sounds! I hope you like it!",
"author": "Babis Kouvalis",
"file_hash": "f91c691e94ada2f3c8b94823f0cd0342fd1b9f0cd48fce49d35a15baa2da971d",
"related": [120, 83, 251, 114, 104],
"license": "public",
"tags": ["djent", "chug", "guitar"],
"apps": ["guitarix"],
"formats": ["gx"],
"mirrors": [],
"more_info": ["https://youtu.be/JRRFaSC7WPY"],
"favorite_count": 2,
"url": "https://musical-artifacts.com/artifacts/115.json",
"download_count": 218,
"file": "https://musical-artifacts.com/artifacts/115/D-Juntu_.gx"
}
You can query additional data provided by the application to help you filter your searches. Currently the data is available for licenses, tags, apps and file formats.
GET /licenses.json
curl https://musical-artifacts.com/licenses.json
[
{ id: 1,
name: 'Public Domain',
short_name: 'public',
license_type: 'public'
},
{ id: 2,
name: 'Creative Commons Attribution 4.0 Unported License.',
short_name: 'by',
license_type: 'cc'
},
{ id: 3,
name: 'Creative Commons Attribution-ShareAlike 4.0 Unported License.',
short_name: 'by-sa',
license_type: 'cc'
},
...
]
GET /searches/tags.json
You can also filter the searches via the q=term parameter
GET /searches/tags.json?q=term
If you want to you can skip the .json on the URL, so this is also a valid call:
GET /searches/tags?q=search
curl https://musical-artifacts.com/searches/tags.json
# ["preset","guitar","distortion","rock","heavy metal","clean","reverb","piano", ... ]
curl https://musical-artifacts.com/searches/tags.json?q=gui
# ["guitar", "gui"]
GET /searches/apps.json
Like tags, you can skip the '.json' in the URL and filter via the 'q' parameter.
curl https://musical-artifacts.com/searches/apps.json
# ["guitarix","zynaddsubfx","yoshimi","linuxsampler","qsampler","fantasia","fluidsynth","qsynth","carla","timidity","sf2","ardour", "helm"]
curl https://musical-artifacts.com/searches/apps.json?q=helm
# ["helm"]
GET /searches/formats.json
Like tags, you can skip the '.json' in the URL and filter via the 'q' parameter.
curl https://musical-artifacts.com/searches/formats.json
# ["gx","xmz","xiz","xpf","gig","sf2","sfz","zip","bz2","tar.xz","xz"]
curl https://musical-artifacts.com/searches/formats.json?q=g
# ["gx", "gig"]
When using the json API, we can't use HTTP and cookie based login to authenticate users, so instead we use a scheme called JWT or Json Web Tokens.
This works in a few steps:
POST /api/auth_token
{"auth": { "email": "youremail", "password": "yourpassword" } }
Here's an example with curl:
# posting the fields
curl https://musical-artifacts.com/api/auth_token -F 'auth[email]=peter@vandergra.af' -F 'auth[password]=12345678'
# or posting JSON data on the body
curl https://musical-artifacts.com/api/auth_token -d '{"auth": {"email": "peter@vandergra.af", "password": "12345678"}}' -H "Content-Type: application/json"
The server will give you back a json token, here's a sample value:
{"jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9"}
Store this value, because it will be used instead of the user email/password and is valid for one week (I'm open to changing this value to a bigger time frame).
Authorization: bearer [jwt-token]
POST /artifacts.json
{"artifact": { "name": "artifact's name", "author": "author's name", ... } }
To create a new artifact post to the /artifacts.json URL with the artifact's parameters. Include the Authorization: bearer [jwt-token] in the request, where jwt-token is the one you got on the previous step. Here's a curl example:
curl -F "artifact[name]=The Door" -F "artifact[author]=Hammil" -F "artifact[license_id]=1" -F "artifact[file]=@The_Door.sf2" -F "artifact[tag_list]=soundfont" -H "Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9" https://musical-artifacts.com/artifacts.json
# JSON Response (the same as if you had used a GET for the artifact's URL)
{
"id": 126, "name": "The Door", "tags": ["soundfont"],
..., "file": "/artifacts/126/The_Door.sf2", "owner": true
}
Authorization: bearer jwt-token
PUT /artifacts/ID.json
{"artifact": { "name": "artifact's name", "author": "author's name", ... } }
Just like creating an artifact, but this time you'll have to issue a PUT request to the artifact path, which can be constructed with it's id (it's the same URL used to access the single artifact). Here's a curl example:
curl -X PUT -F "artifact[author]=Peter Hammil" -F "artifact[tag_list]=soundfont, generator" -H "Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9" https://musical-artifacts.com/artifacts/126.json
# JSON Response (the same as if you had used a GET for the artifact's URL)
{
"id": 126, ... "author": "Peter Hammil",
"tags": ["soundfont", "generator"], ..., "owner": true
}
Remember you can only edit artifacts which have been created by the current user which request the token.
The following fields can be populated via create or edit calls:
- name: a string
- description: a string
- author: a string
- file: a file
- more_info_urls: a list of comma separated URLs
- mirrors: a list of comma separated URLs
- software_list: a list of comma separated app names (use app search API call for values)
- tag_list: a list of comma separated tags (use tag search API call for values)
- file_format_list: a list of comma separated file formats (see the formats search API call for values)
- license_id: the ID for a license (see license API call to get values)
- extra_license_text: a string
The path '/my_artifacts' will return a list of the artifacts owned by the currently logged user. This can also be used with API authentication to return this list as a json object.
Authorization: bearer jwt-token
GET /my_artifacts.json
The response is the same as a GET to '/artifacts.json', but will return only the user artifacts.
The API is limited to 60 HTTP requests per minute.