Metadata Types API Documentation

Metadata types are the custom fields a library tags its tracks with: genres, moods, instruments, a release date, a rating, and so on. Each has a data type that decides what values it holds and which search operators apply to it. Metadata types use Spondulix’s own IDs. A type that is not of tags carries "track_keys": { "value": "release_date" } and a tags_count of null. Reading is open to every collaborator; creating, updating, deleting and reordering need the editor role.

A tag type either uses external IDs for its tags or does not (has_external_id). With them, which is the default, every tag carries your own ID and is addressed by it. Without, tags are addressed by name, and tracks can bring new tags with them.

Endpoints

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

Retrieve the metadata types in a library, in display order.

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)
per_page	integer	Records per page, up to 200 (default: 25)

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/metadata_types?page=2"
    },
    "metadata_types": [
        {
            "id": 19,
            "library_id": 2,
            "name": "catalog",
            "data_type": "tag",
            "multiple": false,
            "sortable": false,
            "include_in_prompt": true,
            "has_external_id": true,
            "position": 1,
            "created_at": "2024-08-13T23:36:45.788-05:00",
            "updated_at": "2024-08-13T23:44:35.895-05:00",
            "track_keys": { "by_id": "catalog_id", "by_name": "catalog_name", "objects": "catalog" },
            "tags_count": 77,
            "url": "https://app.spondulix.ai/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,
            "has_external_id": true,
            "position": 2,
            "created_at": "2024-08-13T23:33:54.204-05:00",
            "updated_at": "2024-10-10T11:10:20.149-05:00",
            "track_keys": { "by_id": "genre_id", "by_name": "genre_name", "objects": "genre" },
            "tags_count": 77,
            "url": "https://app.spondulix.ai/api/v1/libraries/2/metadata_types/17"
        }
    ],
    "built_in_fields": [
        { "name": "id", "type": "integer" },
        { "name": "active", "type": "flag" },
        { "name": "bpm", "type": "range" },
        { "name": "title", "type": "text" },
        { "name": "style_alikes", "type": "string" },
        { "name": "lyrical_theme", "type": "vector" }
    ]
}

Response Fields

Field	Type	Description
pagination	object	Contains pagination information
metadata_types	array	List of metadata type objects
built_in_fields	array	The fields every library can be searched on, each with its `name` and `type`. See query operators.
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)
has_external_id	boolean	Whether the type’s tags carry your own IDs and are addressed by them (only applicable for tags)
position	integer	Display order position
created_at	string	Timestamp of when the metadata type was created
updated_at	string	Timestamp of when the metadata type was last updated
track_keys	object	The keys a track’s JSON uses for this type: what `GET` writes and what `POST` and `PUT` take
by_id	string \| null	For a tag type: the key that takes external IDs. Null when the type has none.
by_name	string	For a tag type: the key that takes names
objects	string	For a tag type: the key that takes objects with `id` and `name`
value	string	For any other type: the key that takes the value
tags_count	integer \| null	Number of tags, for a tag type
url	string	URL of the metadata type

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 metadata type.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Request Body

Wrap the fields in a metadata_type key.

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 a track can carry several values (always false for flags and text)	No
sortable	boolean	Whether values can be sorted (tags only)	No
include_in_prompt	boolean	Whether the type and its tags are described to the model in searches (tags only)	No
has_external_id	boolean	Whether the type’s tags carry your own IDs (tags only; default: true)	No
position	integer	Display order position. A type created without one goes last.	No

{
    "metadata_type": {
        "name": "genre",
        "data_type": "tag",
        "multiple": true,
        "include_in_prompt": true
    }
}

Response

{
    "id": 1,
    "library_id": 2,
    "name": "genre",
    "data_type": "tag",
    "multiple": true,
    "sortable": false,
    "include_in_prompt": true,
    "has_external_id": true,
    "position": 1,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-19T13:36:56.251-05:00",
    "track_keys": { "by_id": "genre_ids", "by_name": "genre_names", "objects": "genres" },
    "tags_count": 77,
    "url": "https://app.spondulix.ai/api/v1/libraries/2/metadata_types/1"
}

HTTP Response Codes

Code	Description
`201 Created`	Successful creation
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID
`422 Unprocessable Content`	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,
    "has_external_id": true,
    "position": 1,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-19T13:36:56.251-05:00",
    "track_keys": { "by_id": "genre_ids", "by_name": "genre_names", "objects": "genres" },
    "tags_count": 77,
    "url": "https://app.spondulix.ai/api/v1/libraries/2/metadata_types/1"
}

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. PATCH works the same way, and only the fields you send change.

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
has_external_id	boolean	Whether the type’s tags carry your own IDs (tags only)	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,
    "has_external_id": true,
    "position": 2,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-20T10:15:30.123-05:00",
    "track_keys": { "by_id": "updated_genre_ids", "by_name": "updated_genre_names", "objects": "updated_genres" },
    "tags_count": 77,
    "url": "https://app.spondulix.ai/api/v1/libraries/2/metadata_types/1"
}

HTTP Response Codes

Code	Description
`200 OK`	Successful update
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID or metadata type ID
`422 Unprocessable Content`	Invalid request (see response body for details)

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

Delete a metadata type, along with its tags and every value tracks hold for it.

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
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID or metadata type ID

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

Update the display order of the metadata types in one request. The IDs are the metadata type IDs from this endpoint; a type left out of the list keeps its position.

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
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID or metadata type ID