Quickstart: MusicAPI Core

You get your keys, connect your own music account as a test user, and read its playlists with one API call.

1. Create an account

   Sign up at app.musicapi.com/admin/signup. Pick what you build: integrating music services into your app, or transferring libraries into your service. See Sandbox and going live for what each choice turns on.

2. Copy your API keys

   Open API & webhooks in the dashboard. Under API keys, create a key and copy its Client ID and Client Secret. The values show only once. Keep the secret on your server only.

3. Add a return URL

   Open Settings and add an Accepted Return URL: the page of your app that the user comes back to after the sign-in. For a first test, any URL you control works, for example http://localhost:3000/callback.

4. Turn on one service

   Open Integrations and enable a service, for example Spotify. A transferring sign-up has ready-made integrations. An integrating sign-up adds its own developer app first: see Set up Spotify.

5. Connect yourself

   Open the hosted sign-in in your browser, pick the service and sign in.

6. Read your playlists

   Take the integrationUserUUID from the callback and call the API.

1. Store your keys

Put the two values into the environment of your backend as MUSICAPI_CLIENT_ID and MUSICAPI_CLIENT_SECRET, from your secret store. Every example on this site reads them from there. Your Client ID is $MUSICAPI_CLIENT_ID.

2. Open the hosted sign-in

Your account slug goes into the path. The returnUrl must match one of your Accepted Return URLs.

https://app.musicapi.com/{slug}?returnUrl={returnUrl}

The user picks a service, signs in and comes back to your return URL. The full list of query parameters is in Start a sign-in.

3. Read the callback

The return URL gets a data64 query parameter: base64-encoded JSON. Decode it on your server.

const params = new URL(request.url, "https://example.com").searchParams;
const data = JSON.parse(Buffer.from(params.get("data64"), "base64").toString("utf8"));
 
if (data.authModel.status !== "success") {
  throw new Error(`Sign-in failed: ${data.authModel.errorType ?? data.authModel.error}`);
}
const integrationUserUUID = data.integrationUserUUID; // store it with your user

{
  "integration": {
    "type": "spotify",
    "isSuperPrivate": false,
    "returnUrl": "https://api.musicapi.com/callback/spotify"
  },
  "authModel": {
    "uuid": "a1869581-38b2-4268-aee2-a4c2355efeb0",
    "status": "success",
    "error": null,
    "errorType": null
  },
  "integrationUserUUID": "3f0b8c1e-6a4d-4c7a-9a55-2f1e7d9b0c11"
}

The integrationUserUUID is the id of this connected account. Store it next to your own user.

4. Read the playlists

curl "https://api.musicapi.com/api/3f0b8c1e-6a4d-4c7a-9a55-2f1e7d9b0c11/playlists" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"

{
  "results": [
    {
      "id": "37i9dQZF1DXcBWIGoYBM5M",
      "name": "Road trip",
      "totalItems": 42,
      "imageUrl": "https://images.example.com/road-trip.jpg",
      "isOwner": true
    }
  ],
  "nextParam": "eyJvZmZzZXQiOjUwfQ==",
  "totalItems": 87
}

A nextParam that is not null means there is another page. Send it back as the nextParam query parameter. See Pagination.

Next steps

• Handle the callback in production, including failures.
• Read and write the library: playlists, liked tracks, albums, artists.
• Handle a 412: the user must connect again.