Skip to main content

Library Management

Cyanite organizes your uploaded tracks into your Library. We represent these recordings with the Library Track object, which contains metadata about your track.

Your library becomes the "haystack" that we search through with our search functionality.

The Library Track Object​

The library track object contains metadata about an individual uploaded track.

PropertyDescription
idThe unique identifier assigned by Cyanite to represent your Library Track
externalIdAn identifier optionally provided by you on creation (or update) of your Library Track, intended to aid with matching Cyanite Tracks to your catalog organization scheme
titleA human readable title for the Library Track
createdAtThe date and time that the track was created in Cyanite
customTagsTags you provide to add additional information to your track. Can be used in the metadata filter field of search endpoints to search specific groups of tracks.

Library Track Lifecycle​

Creation​

Library Tracks are created via the /v1/library-tracks endpoint. For a complete guide to the track upload process and retrieval of model outputs associated with the track, please review our introduction guide.

When a track is created, it's initial state is PENDING, while it is awaiting upload. Once the track is uploaded, it's state will move to either AVAILABLE in the case that the upload was successful, or REJECTED otherwise.

Listing and Searching​

Once Library Tracks are created, it's possible to query your library for tracks matching certain criteria including:

  • Metadata criteria
  • Prompt search criteria
  • Track similarity criteria

Filtering is available on the library track listing endpoint.

note

The library track listing endpoint is paginated, using the limit and cursor query parameters, so it is possible to page through your entire library. You can also use the order query parameter to sort your listing results by their creation time in chronological or reverse chronological order.

The library track listing endpoint accepts criteria in its query parameters to filter the results.

ParameterDescription
nameFilter by track name
externalIdQuery using your own ID space
statusFilter based on the status of the track
updatedSinceShow only tracks that have been updated since a provided date
customTagsShow only tracks that have been tagged with a given custom tag

Example queries​

note

All example queries additionally require an api key as documented, provided in the header as follows: -H "x-api-key: ${CYANITE_API_KEY} - however, this has been omitted from each example for brevity.

Retrieve all tracks tagged with a custom tag that represents a specific artist

curl https://rest-api.cyanite.ai/v1/library-tracks/?customTags=artist:123

Retrieve a track that matches the externalId it's associated with

curl "https://rest-api.cyanite.ai/v1/library-tracks/?externalId=f8e10ab"

Retrieve all rejected tracks since the first of July 2026

curl "https://rest-api.cyanite.ai/v1/library-tracks?status=REJECTED&updatedSince=2026-07-01T00:00:00"

Searching​

For more advanced searching of your Library, you can use our Prompt Search and Similar Track Search products, to find tracks based on a natural language description of the result you would like, or tracks that are similar to an existing track (or tracks) you specify.

For more information on searching, see our search guide.

Metadata updates​

It's possible to modify the metadata associated with your Library Track using the Update Library Track endpoint. You can add custom tags, an external ID, or modify the name of the track.

Add an custom tag representing an artist to the given track

curl -X PATCH https://rest-api.cyanite.ai/v1/library-tracks/{id} \
-d '{"customTags": ["artist:f8e10ab"]}'

Remove the externalId from the track

curl -X PATCH https://rest-api.cyanite.ai/v1/library-tracks/{id} \
-d '{"externalId": null}'

Deletion​

When tracks are no longer needed, they can be deleted and removed from Cyanite.

curl -X DELETE https://rest-api.cyanite.ai/v1/library-tracks/{id}

Do you need to preserve a Library Track, but hide it from search results? We recommend setting a Custom Tag on the track, and then using the metadata filter functionality built into our search features to filter tracks matching that tag out of your search results.

Summary​

In this guide, we've covered:

  • The contents of a Cyanite Library Track object
  • The lifecycle of a Libary Track
  • How to retrieve tracks from your library based on their attributes

Next: