Metadata Tags API Documentation

Metadata tags are the values of a tag-type metadata type: the individual genres, moods, instruments and so on that tracks are tagged with.

Tags can be created through the tracks endpoint, which adds missing tags as tracks are uploaded. This endpoint lists tags and lets you maintain them directly: rename them, fix their external IDs or change their order. Its bulk endpoint is the way to load a type’s tags before loading tracks, which for a type with external IDs is the only way short of the object form on a track. Reading is open to every collaborator; creating, updating and deleting need the editor role.

Tags of a type that uses external IDs are addressed by your ID for them. Tags of a type that does not are addressed by name, escaped for a URL: .../metadata_tags/hip%20hop. Names are stored in lower case with surrounding and repeated white space removed, and are matched the same way, so Hip Hop finds hip hop.

Endpoints

GET /api/v1/libraries/{library_id}/metadata_types/{metadata_type_id}/metadata_tags

Retrieve the tags of a metadata type, in their display order.

Path Parameters

Query Parameters

Response

{
    "pagination": {
        "total_entries": 15,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 1
    },
    "metadata_tags": [
        {
            "id": 101,
            "external_id": 101,
            "metadata_type_id": 17,
            "name": "classical",
            "position": 1,
            "created_at": "2024-08-13T23:33:54.204-05:00",
            "updated_at": "2024-10-10T11:10:20.149-05:00",
            "tracks_count": 42,
            "url": "https://app.spondulix.ai/api/v1/libraries/2/metadata_types/17/metadata_tags/101",
            "tracks_url": "https://app.spondulix.ai/api/v1/libraries/2/metadata_types/17/metadata_tags/101/tracks"
        }
    ]
}

Response Fields

HTTP Response Codes

POST /api/v1/libraries/{library_id}/metadata_types/{metadata_type_id}/metadata_tags

Create a metadata tag.

Path Parameters

Request Body

Wrap the fields in a metadata_tag key.

Within a metadata type, names must be unique when the type does not use external IDs, and external IDs must be unique when it does.

{
    "metadata_tag": {
        "name": "classical",
        "external_id": 101,
        "position": 1
    }
}

Response

Returns the created tag as shown in the list response.

HTTP Response Codes

GET /api/v1/libraries/{library_id}/metadata_types/{metadata_type_id}/metadata_tags/{id}

Retrieve a metadata tag.

Path Parameters

Response

{
    "id": 101,
    "external_id": 101,
    "metadata_type_id": 17,
    "name": "classical",
    "position": 1,
    "created_at": "2024-08-13T23:33:54.204-05:00",
    "updated_at": "2024-10-10T11:10:20.149-05:00",
    "tracks_count": 42,
    "url": "https://app.spondulix.ai/api/v1/libraries/2/metadata_types/17/metadata_tags/101",
    "tracks_url": "https://app.spondulix.ai/api/v1/libraries/2/metadata_types/17/metadata_tags/101/tracks"
}

HTTP Response Codes

PUT /api/v1/libraries/{library_id}/metadata_types/{metadata_type_id}/metadata_tags/{id}

Update a metadata tag. PATCH works the same way, and only the fields you send change.

Path Parameters

Request Body

Response

Returns the updated tag.

HTTP Response Codes

DELETE /api/v1/libraries/{library_id}/metadata_types/{metadata_type_id}/metadata_tags/{id}

Delete a metadata tag, removing it from every track that carried it.

Path Parameters

Response

(no response body)

HTTP Response Codes

GET /api/v1/libraries/{library_id}/metadata_types/{metadata_type_id}/metadata_tags/{id}/tracks

Retrieve the tracks that carry the tag, ordered by title, each as the tracks endpoint gives it, under tracks.

Path Parameters

Query Parameters

Response

A list of tracks with a pagination object, as GET .../tracks returns.

HTTP Response Codes

POST /api/v1/libraries/{library_id}/metadata_types/{metadata_type_id}/metadata_tags/bulk

Create or update up to 1000 tags in one request. A tag is matched to one that exists by external ID when the metadata type uses them and by name when it does not; a tag that matches is updated and one that does not is created. The request is all or nothing: if any tag is invalid, none is saved.

Path Parameters

Request Body

{
    "metadata_tags": [
        { "external_id": 101, "name": "classical" },
        { "external_id": 102, "name": "jazz", "position": 5 }
    ]
}

Tags after the thousandth are dropped without an error, so send a longer list as several requests. Give each tag a position when you do: the default counts from 1 in every request.

Response

{ "created": 1, "updated": 1 }

HTTP Response Codes

A 422 for an invalid tag names each by its place in the list, counting from 0:

{
    "message": "1 of 2 tags were invalid; nothing was saved",
    "failures": [
        {
            "index": 1,
            "tag": { "name": "" },
            "errors": { "name": ["can't be blank"] }
        }
    ]
}

POST /api/v1/libraries/{library_id}/metadata_types/{metadata_type_id}/metadata_tags/sort

Update the display order of the tags in one request. This endpoint backs the drag-and-drop ordering in the web interface and takes Spondulix’s internal tag IDs, which the API does not return; to reorder tags through the API, set position on each tag with the update endpoint instead.

Path Parameters

Request Body

Response

(no response body)

HTTP Response Codes