Skip to content
HooprB2B
Access

Get started

Quickstart

From zero to your first catalog response in about five minutes.

Before you begin

You need a client_id and client_secret from your Hoopr account manager, and your assigned base host. Use your hpr_test_… secret while integrating.

Step 1 — Get an access token

Exchange your credentials for a Bearer token. Tokens live one hour — cache and reuse until they near expiry.

POST /v1/auth/token
curl -X POST "https://<your-b2b-host>/v1/auth/token" \
  -H "Content-Type: application/json" 
  -d '{"grant_type":"client_credentials","client_id":"<client_id>","client_secret":"<client_secret>"}'

You’ll receive:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "catalog:read search",
    "mode": "test"
  },
  "error": { "code": 0, "message": "Token issued" }
}

Step 2 — Call the catalog

Send the token as Authorization: Bearer <token> on every other request. Here we browse music tracks tagged electronic.

GET /v1/tracks
curl "https://<your-b2b-host>/v1/tracks?type=music&filterSlugs=electronic&pageSize=10" \
  -H "Authorization: Bearer $TOKEN"

A paginated list of track objects comes back:

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

Step 3 — Play a track

Each track includes a streamUrl — a signed URL valid for about 30 minutes. Drop it straight into an <audio> element or your player, and re-fetch the track when it expires.

const track = data.items[0];
const audio = new Audio(track.streamUrl);
audio.play();

Keep your secret server-side

All calls are server-to-server. Never ship client_secret (or even long-lived tokens) to a browser or mobile client.

What’s next

Read Authentication for token lifecycle and scopes, Pagination & filtering to refine results, and the API reference for every endpoint.

PreviousIntroductionNext Authentication