Core concepts

The track object

The track is the core resource of the catalog. It carries audio metadata, related artists and filters, and two URLs — one cacheable, one signed and short-lived.

{
  "id": "9b1c0f2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
  "name": "Midnight Drive",
  "slug": "midnight-drive",
  "type": "music",
  "bpm": "120",
  "songKey": ["A min"],
  "timeSignature": "4/4",
  "durationSeconds": 184,
  "region": "IN",
  "releaseDate": "2024-03-01T00:00:00.000Z",
  "hasVocals": false,
  "isPRO": false,
  "tags": ["energetic", "drive"],
  "artists": [
    { "id": "a1b2c3d4", "name": "Nova", "role": "COMPOSER", "isPrimary": true }
  ],
  "filters": [
    { "id": "f1a2b3c4", "name": "Electronic", "slug": "electronic", "type": "genre" },
    { "id": "f2b3c4d5", "name": "Energetic",  "slug": "energetic",  "type": "mood" }
  ],
  "artworkUrl": "https://cdn.hoopr.example/musics/9b1c.../image.jpg",
  "streamUrl": "https://cdn.hoopr.example/musics/9b1c.../audio.mp3?X-Goog-Expires=1800&X-Goog-Signature=..."
}

Track fields

idstringoptional
Stable UUID for the track.
namestringoptional
Display name.
slugstringoptional
URL-safe identifier; used to fetch a single track.
typeenumoptional
One of music or sfx.
bpmstringoptional
Tempo in beats per minute, as a string.
songKeystring[]optional
Musical key(s), e.g. ["A min"].
timeSignaturestringoptional
Time signature, e.g. 4/4.
durationSecondsintegeroptional
Length of the track in seconds.
regionstringoptional
Region code, e.g. IN.
releaseDatestringoptional
ISO 8601 date string.
hasVocalsbooleanoptional
Whether the track contains vocals.
isPRObooleanoptional
Whether the track is registered with a performing-rights organization.
tagsstring[]optional
Free-text descriptive tags.
artistsobject[]optional
Contributors, each { id, name, role, isPrimary }.
filtersobject[]optional
Catalog filters, each { id, name, slug, type }.
artworkUrlstringoptional
Plain, cacheable CDN link to the cover artwork.
streamUrlstringoptional
Short-lived signed URL for streaming the audio.

streamUrl is short-lived

streamUrl is a signed URL valid for 30 minutes. Use it to play or stream within that window. Do not store or share it long-term — when it expires, re-fetch the track for a fresh URL. By contrast, artworkUrl is a plain, cacheable CDN link.

Caching track responses

If you cache track responses (e.g. in Redis), cap the TTL at 30 minutes max so a cached streamUrl never outlives its signature. You may cache metadata freely, but always treat streamUrl as valid for no more than 30 minutes.

PreviousResponse format Next Pagination & filtering