Skip to content
HooprB2B
Access

API reference

List / browse tracks

Page through the catalog with optional free-text and structured filters. Returns a paginated list of track objects.

GET/v1/tracks
scopecatalog:read
Query parameters
  • pageintegeroptionaldefault 1
    Page number.
  • pageSizeintegeroptionaldefault 20
    Items per page (max 100).
  • searchstringoptional
    Free-text match on track name.
  • typeenumoptional
    music or sfx.
  • hasVocalsbooleanoptional
    Filter vocal vs. instrumental tracks.
  • filterIdscsv of UUIDsoptional
    Match tracks tagged with all of these filter ids.
  • filterSlugscsv of slugsoptional
    Same, by slug — e.g. electronic,energetic.

Request

GET /v1/tracks
curl "https://<your-b2b-host>/v1/tracks?type=music&hasVocals=false&filterSlugs=electronic,energetic&page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"

Response

Note the streamUrl on each track is a signed URL valid for ~30 minutes — see The track object.

{
  "data": {
    "totalRecords": 1280,
    "totalPages": 64,
    "currentPage": 1,
    "pageSize": 20,
    "items": [
      {
        "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=..."
      }
    ]
  },
  "error": { "code": 0, "message": "OK" }
}

Errors

HTTPerror.typeMeaning
400invalid_requestA query parameter failed validation.
401invalid_tokenToken missing, malformed or expired.
403insufficient_scopeToken lacks catalog:read.
429rate_limitedOver 600 requests/minute.
PreviousGet access tokenNext Search tracks