Tracks API Documentation

Documentation for the Tracks REST API endpoint. Tracks represent musical compositions in a library, including metadata, rights information, and composition details.

Metadata tags, composers, and publishers can be added to the index by using the object form in the track structure. Note that items will not be updated using this method, but will be added if missing.

Endpoints

GET /api/v1/libraries/{library_id}/tracks

Retrieve a list of tracks for a specific library.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Query Parameters

Name	Type	Description
page	integer	Page number for pagination (default: 1)

Response

{
    "pagination": {
        "total_entries": 34,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 2,
        "next_page": 2,
        "next_page_url": "http://127.0.0.1:3003/api/v1/libraries/2/tracks?page=2"
    },
    "tracks": [
        {
            "id": 999,
            "library_id": 2,
            "title": "Drunken Daisy - You Gotta Have Banjo in the Band",
            "description": "An energetic tune that is part bluegrass and part Irish folk dance...",
            "lyrics": "",
            "lyrics_chorus_only": null,
            "active": true,
            "instrumental": true,
            "explicit": false,
            "clean_available": false,
            "public_domain": false,
            "bpm": null,
            "duration": 185,
            "isrc": null,
            "style_alikes": ["chieftains", "clancy brothers", "flatt and scruggs"],
            "catalog_id": 2,
            "genre_id": 3,
            "subgenre_ids": [17, 169],
            "instrument_ids": [1960, 1943, 1782, 1698],
            "tracks_composers": [
                {
                    "composer_id": 186,
                    "share": "100.0"
                }
            ],
            "tracks_publishers": [
                {
                    "publisher_id": 2,
                    "share": "50.0"
                },
                {
                    "publisher_id": 37,
                    "share": "50.0"
                }
            ],
            "created_at": "2024-08-19T12:42:55.454-05:00",
            "updated_at": "2024-10-16T17:10:42.698-05:00",
            "url": "http://127.0.0.1:3003/api/v1/libraries/2/tracks/999"
        }
    ]
}

Response Fields

Field	Type	Description
id	integer	External ID of the track
library_id	integer	ID of the library the track belongs to
title	string	Title of the track (max 255 chars)
description	string	Description of the track (max 1500 chars)
lyrics	string	Full lyrics of the track (max 5000 chars)
lyrics_chorus_only	string	Chorus lyrics of the track (max 5000 chars)
active	boolean	Whether the track is active
instrumental	boolean	Whether the track is instrumental
explicit	boolean	Whether the track contains explicit content
clean_available	boolean	Whether a clean version is available
public_domain	boolean	Whether the track is in the public domain
bpm	integer	Beats per minute
duration	integer	Duration in seconds
isrc	string	International Standard Recording Code (12 chars)
style_alikes	array	List of similar style references
tracks_composers	array	List of composer assignments with shares
tracks_publishers	array	List of publisher assignments with shares
[metadata_type]_id	integer	Single value for tag-type metadata
[metadata_type]_ids	array	Multiple values for tag-type metadata
[metadata_type]	mixed	Value for non-tag metadata types
created_at	string	Creation timestamp
updated_at	string	Last update timestamp
url	string	URL to the track’s details

POST /api/v1/libraries/{library_id}/tracks

Create a new track.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Request Body

Field	Type	Description	Required
id	integer	External ID for the track	Yes
title	string	Title of the track	Yes
description	string	Description of the track	No
lyrics	string	Full lyrics	No
lyrics_chorus_only	string	Chorus lyrics	No
active	boolean	Track status	No
instrumental	boolean	Instrumental status	No
explicit	boolean	Explicit content flag	No
clean_available	boolean	Clean version available	No
public_domain	boolean	Public domain status	No
bpm	integer	Beats per minute	No
duration	integer	Duration in seconds	No
isrc	string	ISRC code	No
style_alikes	array	Similar style references	No
[metadata_type]_id	integer	Single tag value	No
[metadata_type]_ids	array	Multiple tag values	No
[metadata_type]	mixed	Non-tag metadata value	No
tracks_composers	array	Composer assignments	No
tracks_publishers	array	Publisher assignments	No

Metadata can be specified in several formats:

Single tags: genre_id: 3 or genre_name: "rock"
Multiple tags: subgenre_ids: [17, 169] or subgenre_names: ["blues", "folk"]
Object format: genres: [{ id: 3, name: "rock" }]

Composers and publishers can be specified with existing IDs or new records:

{
    "tracks_composers": [
        {
            "composer_id": 186,
            "share": 100.0
        },
        {
            "composer": {
                "id": 187,
                "name": "New Composer",
                "pro_id": "123",
                "ipi_number": "456"
            },
            "share": 50.0
        }
    ]
}

Response

Returns the created track object with HTTP status 201.

HTTP Response Codes

Code	Description
`201 Created`	Successful creation
`404 Not Found`	Invalid library ID
`422 Unprocessable Entity`	Invalid request (see response body for details)

GET /api/v1/libraries/{library_id}/tracks/{id}

Retrieve details of a specific track.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	External ID of the track	Yes

Response

Returns the track object as shown in the index response.

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID or track ID

PUT /api/v1/libraries/{library_id}/tracks/{id}

Update a track. Accepts the same parameters as the create endpoint.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	External ID of the track	Yes

Response

Returns the updated track object.

HTTP Response Codes

Code	Description
`200 OK`	Successful update
`404 Not Found`	Invalid library ID or track ID
`422 Unprocessable Entity`	Invalid request (see response body for details)

DELETE /api/v1/libraries/{library_id}/tracks/{id}

Delete a track.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	External ID of the track	Yes

Response

No response body.

HTTP Response Codes

Code	Description
`204 No Content`	Successful deletion
`404 Not Found`	Invalid library ID or track ID