Metadata Types API Documentation

Documentation for the Metadata Types REST API endpoint. Metadata Types define custom fields for tracks in a library. Note the these updates can also be performed in the interactive web interface.

Endpoints

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

Retrieve a list of metadata types 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/metadata_types?page=2"
    },
    "metadata_types": [
        {
            "id": 19,
            "library_id": 2,
            "name": "catalog",
            "data_type": "tag",
            "multiple": false,
            "sortable": false,
            "include_in_prompt": true,
            "position": 1,
            "created_at": "2024-08-13T23:36:45.788-05:00",
            "updated_at": "2024-08-13T23:44:35.895-05:00",
            "url": "http://127.0.0.1:3003/api/v1/libraries/2/metadata_types/19"
        },
        {
            "id": 17,
            "library_id": 2,
            "name": "genre",
            "data_type": "tag",
            "multiple": false,
            "sortable": false,
            "include_in_prompt": true,
            "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"
        }
    ]
}

Response Fields

Field Type Description
pagination object Contains pagination information
metadata_types array List of metadata type objects
id integer Unique identifier for the metadata type
library_id integer ID of the library the metadata type belongs to
name string Name of the metadata type (max 30 chars, lowercase letters and underscores only)
data_type string Type of data stored (“tag”, “flag”, “integer”, “float”, “string”, “text”, “date”)
multiple boolean Whether multiple values are allowed (always false for flags and text)
sortable boolean Whether values can be sorted (only applicable for tags)
include_in_prompt boolean Whether to include in AI prompts (only applicable for tags)
position integer Display order position
has_external_id boolean Whether external IDs are used (only applicable for tags)
created_at string Timestamp of when the metadata type was created
updated_at string Timestamp of when the metadata type was last updated

HTTP Response Codes

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

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

Create a new metadata type.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes

Request Body

Field Type Description Required
name string Name of the metadata type (max 30 chars, lowercase letters and underscores only) Yes
data_type string Type of data (“tag”, “flag”, “integer”, “float”, “string”, “text”, “date”) Yes
multiple boolean Whether multiple values are allowed No
sortable boolean Whether values can be sorted (tags only) No
include_in_prompt boolean Whether to include in AI prompts (tags only) No
position integer Display order position No

Response

{
    "id": 1,
    "library_id": 2,
    "name": "genre",
    "data_type": "tag",
    "multiple": true,
    "sortable": false,
    "include_in_prompt": true,
    "position": 1,
    "has_external_id": true,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-19T13:36:56.251-05:00"
}

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}/metadata_types/{id}

Retrieve details of a specific metadata type.

Path Parameters

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

Response

{
    "id": 1,
    "library_id": 2,
    "name": "genre",
    "data_type": "tag",
    "multiple": true,
    "sortable": false,
    "include_in_prompt": true,
    "position": 1,
    "has_external_id": true,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-19T13:36:56.251-05:00"
}

HTTP Response Codes

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

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

Update a metadata type.

Path Parameters

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

Request Body

Field Type Description Required
name string Name of the metadata type No
data_type string Type of data No
multiple boolean Whether multiple values are allowed No
sortable boolean Whether values can be sorted No
include_in_prompt boolean Whether to include in AI prompts No
position integer Display order position No

Response

{
    "id": 1,
    "library_id": 2,
    "name": "updated_genre",
    "data_type": "tag",
    "multiple": true,
    "sortable": true,
    "include_in_prompt": true,
    "position": 2,
    "has_external_id": true,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-20T10:15:30.123-05:00"
}

HTTP Response Codes

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

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

Delete a metadata type.

Path Parameters

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

Response

(no response body)

HTTP Response Codes

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

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

Update the display order of metadata types.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes

Request Body

Field Type Description Required
metadata_type array[integer] Ordered array of metadata type IDs Yes

Response

(no response body)

HTTP Response Codes

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