Web API

The AcousticBrainz server provides a Web API for getting and submitting data.

Base URL: https://acousticbrainz.org

Endpoint Reference

Core data

GET /api/v1/low-level

Get low-level data for many recordings at once.

Example response:

{"mbid1": {"offset1": {document},
           "offset2": {document}},
 "mbid2": {"offset1": {document}}
}

Offset keys are returned as strings, as per JSON encoding rules. If an offset was not specified in the request for an mbid, the offset will be 0.

If the list of MBIDs in the query string has a recording which is not present in the database, then it is silently ignored and will not appear in the returned data.

Query Parameters:
 
  • recording_ids

    Required. A list of recording MBIDs to retrieve

    Takes the form mbid[:offset];mbid[:offset]. Offsets are optional, and should be >= 0

Response Headers:
 
GET /api/v1/count

Get low-level count for many recordings at once. MBIDs not found in the database are omitted in the response.

Example response:

{"mbid1": {"count": 3},
 "mbid2": {"count": 1}
}
Query Parameters:
 
  • recording_ids

    Required. A list of recording MBIDs to retrieve

    Takes the form mbid;mbid.

Response Headers:
 
GET /api/v1/(uuid: mbid)/high-level

Get high-level data for recording with a given MBID.

This endpoint returns one document at a time. If there are many submissions for an MBID, you can browse through them by specifying an offset parameter n. Documents are sorted by the submission time of their associated low-level documents.

You can get the total number of low-level submissions using /<mbid>/count endpoint.

Query Parameters:
 
  • nOptional. Integer specifying an offset for a document.
Response Headers:
 
GET /api/v1/(uuid: mbid)/low-level

Get low-level data for a recording with a given MBID.

This endpoint returns one document at a time. If there are many submissions for an MBID, you can browse through them by specifying an offset parameter n. Documents are sorted by their submission time.

You can the get total number of low-level submissions using the /<mbid>/count endpoint.

Query Parameters:
 
  • nOptional. Integer specifying an offset for a document.
Response Headers:
 
POST /api/v1/(uuid: mbid)/low-level

Submit low-level data to AcousticBrainz.

Request Headers:
 
Response Headers:
 
GET /api/v1/(uuid: mbid)/count

Get the number of low-level data submissions for a recording with a given MBID.

Response Headers:
 

Datasets

POST /api/v1/datasets/

Create a new dataset.

Example request:

{
    "name": "Mood",
    "description": "Dataset for mood classification.",
    "public": true,
    "classes": [
        {
            "name": "Happy",
            "description": "Recordings that represent happiness.",
            "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
        },
        {
            "name": "Sad"
        }
    ]
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Required. Name of the dataset.
  • description (string) – Optional. Description of the dataset.
  • public (boolean) – Optional. true to make dataset public, false to make it private. New datasets are public by default.
  • classes (array) –

    Optional. Array of objects containing information about classes to add into new dataset. For example:

    {
        "name": "Happy",
        "description": "Recordings that represent happiness.",
        "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
    }
    
Response Headers:
 
Response JSON Object:
 
  • success (boolean) – True on successful creation.
  • dataset_id (string) – ID (UUID) of newly created dataset.
PUT /api/v1/datasets/(uuid: dataset_id)/recordings

Add recordings to a class in a dataset.

Example request:

{
    "class_name": "Happy",
    "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
}
Request Headers:
 
Request JSON Object:
 
  • class_name (string) – Required. Name of the class.
  • recordings (array) – Required. Array of recoding MBIDs (string) to add into that class.
Response Headers:
 
DELETE /api/v1/datasets/(uuid: dataset_id)/recordings

Delete recordings from a class in a dataset.

Example request:

{
    "class_name": "Happy",
    "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
}
Request Headers:
 
Request JSON Object:
 
  • class_name (string) – Required. Name of the class.
  • recordings (array) – Required. Array of recoding MBIDs (string) that need be deleted from a class.
Response Headers:
 
POST /api/v1/datasets/(uuid: dataset_id)/classes

Add a class to a dataset.

The data can include an optional list of recording ids. If these are included, the recordings are also added to the list. Duplicate recording ids are ignored.

If a class with the given name already exists, the recordings (if provided) will be added to the existing class.

Example request:

{
    "name": "Not Mood",
    "description": "Dataset for mood misclassification.",
    "recordings": ["770cc467-8dde-4d22-bc4c-a42f91e"]
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Required. Name of the class. Must be unique within a dataset.
  • description (string) – Optional. Description of the class.
  • recordings (array) – Optional. Array of recording MBIDs (string) to add into that class. For example: ["770cc467-8dde-4d22-bc4c-a42f91e"].
Response Headers:
 
PUT /api/v1/datasets/(uuid: dataset_id)/classes

Update class in a dataset.

If one of the fields is not specified, it will not be updated.

Example request:

{
    "name": "Very happy",
    "new_name": "Recordings that represent ultimate happiness."
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Required. Current name of the class.
  • new_name (string) – Optional. New name of the class. Must be unique within a dataset.
  • description (string) – Optional. Description of the class.
Response Headers:
 
DELETE /api/v1/datasets/(uuid: dataset_id)/classes

Delete class and all of its recordings from a dataset.

Example request:

{
    "name": "Sad"
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Required. Name of the class.
Response Headers:
 
GET /api/v1/datasets/(uuid: dataset_id)

Retrieve a dataset.

Response Headers:
 
DELETE /api/v1/datasets/(uuid: dataset_id)

Delete a dataset.

PUT /api/v1/datasets/(uuid: dataset_id)

Update dataset details.

If one of the fields is not specified, it will not be updated.

Example request:

{
    "name": "Not Mood",
    "description": "Dataset for mood misclassification.",
    "public": true
}
Request Headers:
 
Request JSON Object:
 
  • name (string) – Optional. Name of the dataset.
  • description (string) – Optional. Description of the dataset.
  • public (boolean) – Optional. true to make dataset public, false to make it private.
Response Headers: