Tracks API Documentation

Tracks are the catalog itself: the title, lyrics, flags, tempo and duration of each recording, its composers and publishers with their shares, the artists it sounds like, and a value for each of the library’s metadata types.

Tracks are addressed by your own external ID. Metadata tags, composers and publishers can be created on the fly from the object forms described below, so a single track upload can carry everything the track needs, and the bulk endpoint takes up to 200 tracks at a time when loading a catalog. What GET gives, PUT and POST take, so a track read from the API can be sent back as it is; library_id, created_at, updated_at and url are accepted and ignored. Reading is open to every collaborator; creating, updating and deleting need the editor role.

Endpoints

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

Retrieve the tracks in a library, ordered by title. With q, only the tracks that have every word of it somewhere in their text: this finds tracks by what is written in them, where the search endpoint finds music by what it is like.

Path Parameters

Query Parameters

Response

{
    "pagination": {
        "total_entries": 34,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 2,
        "next_page": 2,
        "next_page_url": "https://app.spondulix.ai/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": null,
            "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],
            "mood_names": ["calm", "warm"],
            "instrument_ids": [1960, 1943, 1782, 1698],
            "release_date": "2019-04-12",
            "created_at": "2024-08-19T12:42:55.454-05:00",
            "updated_at": "2024-10-16T17:10:42.698-05:00",
            "tracks_composers": [
                { "composer_id": 186, "share": "100.0" }
            ],
            "tracks_publishers": [
                { "publisher_id": 2, "share": "50.0" },
                { "publisher_id": 37, "share": "50.0" }
            ],
            "url": "https://app.spondulix.ai/api/v1/libraries/2/tracks/999"
        }
    ]
}

Response Fields

Metadata keys are named after the library’s metadata types, so they differ from library to library. A type with no value on the track appears as null or an empty array.

HTTP Response Codes

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

Create a track.

Path Parameters

Request Body

Wrap the fields in a track key.

Text longer than a field’s maximum is cut to fit rather than rejected. A key that is not a built-in field or a metadata type is reported as an error.

Blank values. Sending null, an empty string or an empty list removes the value. Optional text fields are stored as null when blank, so “has no description” has exactly one representation and searches can find it with is_null.

Metadata values

Each of the library’s metadata types can be set under its name. The accepted forms depend on the type. Each type’s track_keys in the metadata types response names the exact keys for that type, so a client need not work them out.

Tag types, single-valued:

• genre_id: 3 sets the tag with external ID 3. An ID the type does not have is ignored.
• genre_name: "rock" sets the tag by name. On a type without external IDs a tag that does not exist is created. On a type with them the tag must exist already, since a name alone gives a new tag no ID; use the object form below to create one.
• genre: { "id": 3, "name": "rock" } sets the tag by external ID, creating it with that name if it does not exist. An existing tag is not renamed.
• genre: 3 or genre: "rock" are treated as an ID or a name respectively.

Tag types that allow multiple values take a list in the same forms: subgenre_ids: [17, 169], subgenre_names: ["blues", "folk"] or subgenres: [{ "id": 17, "name": "blues" }]. The list replaces the track’s previous tags of that type.

Other types take the value directly, under the type’s name: release_date: "2019-04-12", rating: 4.5, cover_song: true. A multi-valued type takes a list under the plural name, which replaces the previous values.

Composers and publishers

tracks_composers and tracks_publishers are lists that replace the track’s previous composers or publishers. Each entry carries a share and refers to the record either by external ID or as an object:

{
    "tracks_composers": [
        { "composer_id": 186, "share": 50.0 },
        {
            "composer": {
                "id": 187,
                "name": "New Composer",
                "pro_id": 21,
                "ipi_number": "00000000456"
            },
            "share": 50.0
        }
    ],
    "tracks_publishers": [
        { "publisher": { "id": 2, "name": "Mike's Awesome Music", "pro_id": 21 }, "share": 100.0 }
    ]
}

A composer_id or publisher_id must already exist in the library. An object form creates the record if its id is new and otherwise refers to the existing record without changing it. A credit sent without a share is stored with none and comes back as "share": null. The fields accepted are the same as the composers and publishers endpoints take.

Example

curl -X POST https://app.spondulix.ai/api/v1/libraries/2/tracks \
  -H "Authorization: Bearer your-api-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "track": {
      "id": 1001,
      "title": "Highway Windows Down",
      "lyrics": "Roll the windows down ...",
      "instrumental": false,
      "bpm": 118,
      "duration": 204,
      "genre_name": "indie pop",
      "moods": [{ "id": 12, "name": "upbeat" }, { "id": 40, "name": "summer" }],
      "style_alikes": ["haim", "best coast"],
      "tracks_composers": [{ "composer_id": 186, "share": 100 }]
    }
  }'

Response

Returns the created track as shown in the list response.

HTTP Response Codes

A 409 is rare: the save is retried four times first. Its body is { "message": "The database was busy with a conflicting change; try again (Deadlocked)" }, nothing of the track was saved, and sending it again is safe.

A 422 body lists the problems by field, with metadata and composer problems under base:

{
    "title": ["can't be blank"],
    "base": ["Unknown metadata type: genrre_id", "Composer 187 is invalid: Name can't be blank"]
}

Naming a tag that does not exist on a type with external IDs fails with a message that says what to send instead:

{
    "base": ["The genre tag \"ska\" does not exist, and a new genre needs an id: use genres: [{\"id\": ..., \"name\": \"ska\"}]"]
}

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

Create or update up to 200 tracks in one request. Each track is what POST .../tracks takes. A track whose id is already in the library is updated, and one whose id is not is created.

Each track stands or falls alone. A track that fails is reported and leaves nothing behind, not even the tags, composers or publishers it would have created; the others are saved.

Path Parameters

Request Body

{
    "tracks": [
        { "id": 1001, "title": "Highway Windows Down", "bpm": 118 },
        { "id": 1002, "title": "" }
    ]
}

Response

{
    "created": 1,
    "updated": 0,
    "failures": [
        { "index": 1, "id": 1002, "errors": { "title": ["can't be blank"] } }
    ]
}

Response Fields

HTTP Response Codes

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

Retrieve a track.

Path Parameters

Response

Returns the track as shown in the list response.

HTTP Response Codes

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

Update a track, or create it if there is no track with that ID, so a loader can send every track the same way without asking first. A new track needs a title, as it does on create, and the response is 201 Created. PATCH works the same way. The body takes the same fields as create; only the fields you send change, so a request with just { "track": { "bpm": 124 } } leaves everything else alone. A list field (style_alikes, tags of a multi-valued type, tracks_composers, tracks_publishers) replaces the whole list when it is sent.

Path Parameters

Response

Returns the updated or created track.

HTTP Response Codes

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

Delete a track, along with its metadata values, lyric index entries and any search results that referenced it.

Path Parameters

Response

No response body.

HTTP Response Codes

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

Retrieve the track’s lyric chunks and whether each has been embedded. Lyrics are cut into chunks, the whole and each section, and every chunk is embedded in the background through the library’s embedding batches. The vector itself is never returned. Not paged.

Path Parameters

Response

{
    "lyric_vectors": [
        {
            "id": 169840,
            "position": 0,
            "chunk_type": "full",
            "chunk_text": "1000 feet\n\ni ve got a thousand feet to climb ...",
            "chunk_occurrences": 1,
            "track_chunk_count": 1,
            "chunk_size_share": 1.0,
            "embedding_attempts": 0,
            "embedding_batch_id": null,
            "created_at": "2026-09-16T17:05:25.300-05:00",
            "updated_at": "2026-09-16T17:05:25.300-05:00",
            "embedded": false
        }
    ]
}

Response Fields

HTTP Response Codes