Harvest Public API: Asset URL Updates

From 10 February 2027 we will end support for legacy URLs that have historically been used to retrieve assets from Harvest via the Harvest Public API. Please see below for critical information regarding changes you will need to make to ensure continuity of services. These changes will need to be made by you or your web developers.

What assets are affected?

The following assets are affected by this update:

1. Library artwork
2. Album artwork
3. Album montage audio
4. Album montage waveform data-points
5. Track audio
6. Track waveform image
7. Track waveform data-points
8. Stem audio
9. Stem waveform image
10. Stem waveform data-points
11. Playlist folder/category artwork
12. Playlist artwork
13. Style artwork
14. Member profile artwork
15. Member group logo
16. Member group artwork
17. Member group production artwork
18. Rightholder artwork

If your website or application retrieves any of these assets via the Harvest Public API, then you should check your implementation and make the necessary updates before the cut off date.

What has changed?

Historically, many Harvest asset URLs have included tokens within the URL path itself. For example, track audio may have been accessed in the following way:

Legacy URL: https://<harvest-domain>/assets/samples/{harvest-token}/{track-id}

Note the usage of the "{harvest-token}" here, found within the URL path itself. 

In order to improve cache invalidation processes for assets, we made improvements that saw the token move from the URL path to the URL query string.

New URL: https://<harvest-domain>/assets/audition/{track-id}?token={harvest-token}

What you need to do

If you have a website or application that connects to the Harvest Public API, which draws upon assets held within Harvest, then you must update to the improved Asset URL structure. You should review your website implementation to determine if updates are required.

The following endpoints in the Harvest Public API return asset URLS:

1. Get Service Info
2. Get Member Info
3. Login Member

Each of these endpoints return the same ServiceInfoURLs property in the response:

"ServiceInfoURLs": {
    "DirectDownloadURL": "https://{domain}/assets/downloads/{downloadtoken}",
    "TrackStreamURL": "https://{domain}/assets/samples/{token}/{id}",
    "ProfileImageURL": "https://{domain}/assets/memberprofile/{token}/{id}/{width}/{height}",
    "AlbumMontageSampleURL": "https://{domain}/assets/samples/montage/{token}/{id}",
    "AlbumArtURL": "https://{domain}/assets/albumart/{token}/{id}/{width}/{height}",
    "WaveformURL": "https://{domain}/assets/waveforms/{token}/{id}/{width}/{height}/{color}/{colorblack}/{blackwidth}/{gapwidth}",
    "MontageWaveformURL": "https://{domain}/assets/waveforms/montage/{token}/{id}/{width}/{height}/{color}/{colorblack}/{blackwidth}/{gapwidth}",
    "LibraryLogoUrl": "https://{domain}/assets/librarylogo/{token}/{id}/{width}/{height}",
    "PlaylistArtUrl": "https://{domain}/assets/playlistart/{token}/{id}/{width}/{height}",
    "PlaylistCategoryArtUrl": "https://{domain}/assets/playlistcategoryart/{token}/{id}/{width}/{height}",
    "RightHolderProfileUrl": "https://{domain}/assets/rightholderprofile/{token}/{id}/{width}/{height}",
    "WaveformDataPointUrl": "https://{domain}/assets/waveform_data/{token}/{id}/{dataformat}",
    "StyleArtUrl": "https://{domain}/assets/styleart/{token}/{id}/{width}/{height}",
    "MemberGroupLogoUrl": "https://{domain}/assets/membergrouplogo/{token}/{id}/{width}/{height}",
    "MemberGroupArtUrl": "https://{domain}/assets/membergroupart/{token}/{id}/{width}/{height}",
    "MemberGroupProductionArtUrl": "https://{domain}/assets/membergroupproductionart/{token}/{id}/{width}/{height}",
    "StemStreamURL": "https://{domain}/assets/samples/stem/{token}/{id}",
    "StemWaveformURL": "https://{domain}/assets/waveforms/stem/{token}/{id}/{width}/{height}/{color}/{colorblack}/{blackwidth}/{gapwidth}",
    "StemWaveformDataPointUrl": "https://{domain}/assets/waveform_data/stem/{token}/{id}/{dataformat}"
}

All of these URLs, with the exception of "DirectDownloadURL" were updated. In each case, the {token} moved to the query string as seen below:

"ServiceInfoURLs": {
    "DirectDownloadURL": "https://{domain}/assets/downloads/{downloadtoken}",
    "TrackStreamURL": "https://{domain}/assets/audition/{id}?token={token}&source={source}",
    "ProfileImageURL": "https://{domain}/assets/memberprofile/{id}?token={token}&width={width}&height={height}",
    "AlbumMontageSampleURL": "https://{domain}/assets/audition/montage/{id}?token={token}&source={source}",
    "AlbumArtURL": "https://{domain}/assets/albumart/{id}?token={token}&width={width}&height={height}",
    "WaveformURL": "https://{domain}/assets/waveforms/{id}?token={token}&width={width}&height={height}&color={color}&colorblack={colorblack}&blackwidth={blackwidth}&gapwidth={gapwidth}",
    "MontageWaveformURL": "https://{domain}/assets/waveforms/montage/{id}?token={token}&width={width}&height={height}&color={color}&colorblack={colorblack}&blackwidth={blackwidth}&gapwidth={gapwidth}",
    "LibraryLogoUrl": "https://{domain}/assets/librarylogo/{id}?token={token}&width={width}&height={height}",
    "PlaylistArtUrl": "https://{domain}/assets/playlistart/{id}?token={token}&width={width}&height={height}",
    "PlaylistCategoryArtUrl": "https://{domain}/assets/playlistcategoryart/{id}?token={token}&width={width}&height={height}",
    "RightHolderProfileUrl": "https://{domain}/assets/rightholderprofile/{id}?token={token}&width={width}&height={height}",
    "WaveformDataPointUrl": "https://{domain}/assets/waveform_data/{id}?token={token}&dataformat={dataformat}",
    "StyleArtUrl": "https://{domain}/assets/styleart/{id}?token={token}&width={width}&height={height}",
    "MemberGroupLogoUrl": "https://{domain}/assets/membergrouplogo/{id}?token={token}&width={width}&height={height}",
    "MemberGroupArtUrl": "https://{domain}/assets/membergroupart/{id}?token={token}&width={width}&height={height}",
    "MemberGroupProductionArtUrl": "https://{domain}/assets/membergroupproductionart/{id}?token={token}&width={width}&height={height}",
    "StemStreamURL": "https://{domain}/assets/audition/stem/{id}?token={token}&source={source}",
    "StemWaveformURL": "https://{domain}/assets/waveforms/stem/{id}?token={token}&width={width}&height={height}&color={color}&colorblack={colorblack}&blackwidth={blackwidth}&gapwidth={gapwidth}",
    "StemWaveformDataPointUrl": "https://{domain}/assets/waveform_data/stem/{id}?token={token}&dataformat={dataformat}"
}

In addition, TrackStreamURL, StemStreamURL and AlbumMontageSampleURL also under went one other change that is unique to them. Previously the path would contain /assets/samples/, this was updated to /assets/audition/. 

You should review and update your implementation to ensure that it handles both cases; the legacy format, and the updated format as seen above. Remember to also review for the unique update on track stream and stem stream URLs mentioned above. Once you have made the update and your updates have been released to your website, please notify us so that we can complete the transition of your API key away from the legacy URLs. Once we have completed the transition, the Harvest Public API response for ServiceInfoUrls will shift to the updated response.

If you have any questions, please reach out to our helpful support staff.

Thank you.