API reference

Search tracks

A richer, body-based equivalent of list — convenient for complex filter sets. Returns the same paginated track list shape.

POST/v1/search

scopesearch

Body parameters

querystringoptional
Free-text match on track name.
typeenumoptional
music or sfx.
hasVocalsbooleanoptional
Filter vocal vs. instrumental.
filterIdsstring[]optional
Filter UUIDs to match (all).
filterSlugsstring[]optional
Filter slugs to match, e.g. ["electronic"].
pageintegeroptionaldefault 1
Page number.
pageSizeintegeroptionaldefault 20
Items per page (max 100).

Request

POST /v1/search

curl -X POST "https://<your-b2b-host>/v1/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"drive","type":"music","hasVocals":false,"filterSlugs":["electronic"],"page":1,"pageSize":20}'

Response

{
  "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

HTTP	error.type	Meaning
400	invalid_request	Body failed validation.
401	invalid_token	Token missing, malformed or expired.
403	insufficient_scope	Token lacks the search scope.
429	rate_limited	Over 600 requests/minute.

PreviousList tracks Next Get a track