Metadata Tags API Documentation

Documentation for the Metadata Tags REST API endpoint. Metadata Tags represent predefined values for tag-type metadata fields.

Please note that the normal way to add metadata tags is through the tracks API endpoint. It’s possible to also maintain them using this endpoint.

Endpoints

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

Retrieve a list of metadata tags for a specific metadata type.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
metadata_type_id integer ID of the metadata type Yes

Query Parameters

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

Response

{
    "pagination": {
        "total_entries": 15,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 1,
        "next_page": null,
        "next_page_url": null
    },
    "metadata_tags": [
        {
            "id": 1,
            "metadata_type_id": 17,
            "name": "classical",
            "external_id": 101,
            "position": 1,
            "created_at": "2024-08-13T23:33:54.204-05:00",
            "updated_at": "2024-10-10T11:10:20.149-05:00",
            "url": "http://127.0.0.1:3003/api/v1/libraries/2/metadata_types/17/metadata_tags/101"
        }
    ]
}

Response Fields

Field Type Description
pagination object Contains pagination information
metadata_tags array List of metadata tag objects
id integer Unique identifier for the metadata tag (if metadata type has external IDs)
metadata_type_id integer ID of the parent metadata type
name string Name of the tag (max 255 chars, automatically normalized)
position integer Display order position
created_at string Timestamp of when the tag was created
updated_at string Timestamp of when the tag was last updated
url string URL to access the individual tag’s details

HTTP Response Codes

Code Description
200 OK Successful request
404 Not Found Invalid library ID or metadata type ID

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

Create a new metadata tag.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
metadata_type_id integer ID of the metadata type Yes

Request Body

Field Type Description Required
name string Name of the tag (max 255 chars) Yes
external_id integer External identifier for the tag Yes*
position integer Display order position No

* Required only if the metadata type has external IDs enabled

Response

{
    "id": 1,
    "metadata_type_id": 17,
    "name": "classical",
    "external_id": 101,
    "position": 1,
    "created_at": "2024-08-13T23:33:54.204-05:00",
    "updated_at": "2024-10-10T11:10:20.149-05:00",
    "url": "http://127.0.0.1:3003/api/v1/libraries/2/metadata_types/17/metadata_tags/101"
}

HTTP Response Codes

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

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

Retrieve details of a specific metadata tag.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
metadata_type_id integer ID of the metadata type Yes
id string External ID or name of the tag Yes

Response

{
    "id": 1,
    "metadata_type_id": 17,
    "name": "classical",
    "external_id": 101,
    "position": 1,
    "created_at": "2024-08-13T23:33:54.204-05:00",
    "updated_at": "2024-10-10T11:10:20.149-05:00",
    "url": "http://127.0.0.1:3003/api/v1/libraries/2/metadata_types/17/metadata_tags/101"
}

HTTP Response Codes

Code Description
200 OK Successful request
404 Not Found Invalid library ID, metadata type ID, or tag ID

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

Update a metadata tag.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
metadata_type_id integer ID of the metadata type Yes
id string External ID or name of the tag Yes

Request Body

Field Type Description Required
name string Name of the tag No
external_id integer External identifier for the tag No
position integer Display order position No

Response

{
    "id": 1,
    "metadata_type_id": 17,
    "name": "updated classical",
    "external_id": 101,
    "position": 2,
    "created_at": "2024-08-13T23:33:54.204-05:00",
    "updated_at": "2024-10-10T11:10:20.149-05:00",
    "url": "http://127.0.0.1:3003/api/v1/libraries/2/metadata_types/17/metadata_tags/101"
}

HTTP Response Codes

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

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

Delete a metadata tag.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
metadata_type_id integer ID of the metadata type Yes
id string External ID or name of the tag Yes

Response

(no response body)

HTTP Response Codes

Code Description
204 No Content Successful deletion
404 Not Found Invalid library ID, metadata type ID, or tag ID

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

Update the display order of metadata tags.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
metadata_type_id integer ID of the metadata type Yes

Request Body

Field Type Description Required
metadata_tag array[integer] Ordered array of metadata tag IDs Yes

Response

(no response body)

HTTP Response Codes

Code Description
200 OK Successful update
404 Not Found Invalid library ID, metadata type ID, or tag ID