Skip to main content

Custom Tags

The custom tags feature adds capabilities for cyanite API users to add own custom tags to their library tracks. You can then leverage the advanced search using the new metadata filter to search for tracks by specific custom tags.

Get Custom Tags​

In order to get custom tags of a track, you can use the libraryTrack GraphQL query.

query GetCustomTags {
  libraryTrack(id: 1) {
    ... on LibraryTrack {
      customTags
    }
    ... on LibraryTrackNotFoundError {
      message
    }
  }
}

Update Custom Tags​

You can update custom tags of a track using the customTagsUpdate GraphQL mutation. This mutation will always overwrite the existing custom tags with the new ones. Ensure that all tags comply with the following limits:

  • Tags may include multiple spaces within their text (e.g. cinematic slow build up is a valid tag).
  • The total character count across all custom tags must not exceed 3,000 characters.
mutation UpdateCustomTags {
  customTagsUpdate(input: { libraryTrackId: 1, customTags: ["tag1", "tag2"] }) {
    ... on CustomTagsUpdateSuccess {
      updatedLibraryTrackId
      customTags
    }
    ... on CustomTagsUpdateError {
      code
      message
    }
  }
}

Custom tags become really powerful when combined with our advanced search.

For example, you can search for tracks in your library that matches specific criteria while also having particular custom tags. The example below shows how you might search using a free text prompt but only among tracks that have been tagged with your custom tags.

query AdvancedSearchCustomTags {
  advancedSearch(
    text: "relaxing and quiet song for meditation"
    target: { library: {} }
    metadataFilter: { customTags: { "$in": ["tag1"] }
    first: 50
  ) {
    ... on AdvancedSearchError {
      code
      message
    }
    ... on AdvancedSearchConnection {
      edges {
        node {
          track {
            ... on AdvancedSearchNodeLibraryTrack {
              id
            }
          }
        }
      }
    }
  }
}