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.
| Property | Description |
|---|---|
| id | The unique identifier assigned by Cyanite to represent your Library Track |
| externalId | An 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 |
| title | A human readable title for the Library Track |
| createdAt | The date and time that the track was created in Cyanite |
| customTags | Tags 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.
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.
| Parameter | Description |
|---|---|
| name | Filter by track name |
| externalId | Query using your own ID space |
| status | Filter based on the status of the track |
| updatedSince | Show only tracks that have been updated since a provided date |
| customTags | Show only tracks that have been tagged with a given custom tag |
Example queries
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:
- Learn how to retrieve the tags of your tracks with Tagging, the musical data we can infer from your tracks
- Learn how to search your Cyanite Library by text prompt or similar tracks
- Learn how to detect AI-generated music