Social & Following API

User following, artist following, reposts, and library management endpoints.

Overview

The Social API covers the platform’s social graph — following users and artists, reposting content, and managing the user’s personal library of liked tracks, albums, and artists.

Base URL: https://open.beatpass.ca/api/v1

Authentication: Write operations require a valid Bearer token. Read operations on public profiles use optional auth.

---

User Following

Follow User

POST /api/v1/users/{user}/follow

Unfollow User

POST /api/v1/users/{user}/unfollow

Check Follow Status

GET /api/v1/users/{user}/follow-status

Get User’s Followers

GET /api/v1/users/{user}/followers

Get User’s Followed Users

GET /api/v1/users/{user}/followed-users

---

Artist Following

Follow Artist

POST /api/v1/artists/{artistId}/follow

Unfollow Artist

POST /api/v1/artists/{artistId}/unfollow

Check Artist Follow Status

GET /api/v1/artists/{artistId}/follow-status

Get Artist’s Followers

GET /api/v1/artists/{artistId}/followers

---

Follow Limits

Max Following

5,000 users Maximum accounts a user can follow

Follow Rate

Rate limited Too many follows in quick succession triggers 429

Self-Follow

Not allowed Cannot follow your own account

---

Reposts

Toggle Repost

Toggle repost status for a track. If already reposted, it removes the repost.

POST /api/v1/reposts/toggle

track_id · integer · required

Track ID to repost or un-repost.

Get User’s Reposts

GET /api/v1/users/{user}/reposts

Repost Limits

Limit	Value
Daily repost limit	100 per day
Hourly repost limit	20 per hour
Self-repost	Not allowed

---

User Library

Add to Library

Add a track to the authenticated user’s library (liked tracks).

POST /api/v1/users/me/add-to-library

Remove from Library

Remove a track from the user’s library.

POST /api/v1/users/me/remove-from-library

Get Liked Tracks

GET /api/v1/users/{user}/liked-tracks

Get Liked Albums

GET /api/v1/users/{user}/liked-albums

Get Liked Artists

GET /api/v1/users/{user}/liked-artists

Library Limits

Limit	Value
Max saved items	10,000
Max playlists	100
Max tracks per playlist	500

---

Collections

Collections are curated groupings of content. All collection endpoints require authentication.

List Collections

GET /api/v1/collections

Featured Collections

GET /api/v1/collections/featured

User Collections

GET /api/v1/collections/user

Collection Recommendations

GET /api/v1/collections/recommendations

Create Collection

POST /api/v1/collections

Get Collection

GET /api/v1/collections/{id}

Update Collection

PUT /api/v1/collections/{id}

Delete Collection

DELETE /api/v1/collections/{id}

Play Collection

POST /api/v1/collections/{id}/play

---

User Profile

Get User Profile

Retrieve a user’s public profile. Enhanced data returned when authenticated.

GET /api/v1/user-profile/{user}

Update Profile

Update the authenticated user’s profile.

PUT /api/v1/users/profile/update

Get User’s Playlists

GET /api/v1/users/{user}/playlists

Get Upload Minutes Remaining

Check how many upload minutes a user has remaining on their current plan.

GET /api/v1/users/{user}/minutes-left

user · integer · required

User ID.

Response:

{
  "status": "success",
  "minutesLeft": 120
}

Returns null for minutesLeft if the user’s plan has no minute-based upload restriction.

Get Contact Info

Retrieve a user’s contact information. Rate limited to 30 requests per minute.

GET /api/v1/users/{user}/contact-info

Search Users

GET /api/v1/users/search

---

Notification Preferences

Manage notification delivery channels for the authenticated user. Each notification type (for example new follower, comment reply, or analytics report) has independent channel toggles for email, in_app, and mobile.

Use me for the authenticated user route, or pass the authenticated user’s numeric ID. The backend resolves both forms.

Channel Keys

• email — Email notifications
• in_app — Notification center storage and live activity in open tabs
• mobile — FCM-backed push delivery for registered devices, including supported browsers and mobile apps

Get Notification Subscriptions

Retrieve the authenticated user’s notification configuration, available channels, saved selections, and role-based context.

GET /api/v1/notifications/me/subscriptions

Response:

{
  "status": "success",
  "available_channels": ["email", "in_app", "mobile"],
  "subscriptions": [
    {
      "group_name": "Messages",
      "subscriptions": [
        {
          "name": "Direct Messages",
          "notif_id": "new_message",
          "description": "When you receive a direct message"
        }
      ]
    }
  ],
  "user_selections": [
    {
      "notif_id": "new_message",
      "channels": {
        "email": true,
        "in_app": true,
        "mobile": true
      }
    }
  ],
  "user_context": {
    "is_artist": true,
    "is_verified_artist": false
  }
}

Update Notification Subscriptions

Update one or more notification channel preferences.

PUT /api/v1/notifications/me/subscriptions

selections · array · required

Array of notification preference updates.

selections[].notif_id · string · required

Notification identifier to update, such as new_message.

selections[].channels · object · required

Channel state object keyed by email, in_app, and/or mobile.

Response:

{
  "status": "success"
}

Use the exact backend channel keys in update payloads: email, in_app, and mobile. The legacy browser key is no longer part of the notification settings contract.

---

FCM Device Tokens

Register and manage Firebase Cloud Messaging device tokens for the authenticated user. The API stores tokens only; obtaining the token is the responsibility of the client app through the Firebase SDK.

Register or Refresh FCM Token

Store or refresh an FCM token for the authenticated user.

POST /api/v1/fcm-tokens

token · string · required

FCM registration token returned by the Firebase client SDK.

platform · string

Device platform. Supported values: web, android, ios. Defaults to web.

device_name · string

Optional device label, typically the user agent or app/device name.

Response:

{
  "status": "ok"
}

Tokens are upserted by token value. Re-registering the same token refreshes its metadata and ownership. These FCM token endpoints currently return { "status": "ok" }, while the notification subscription endpoints above use the standard { "status": "success" } response envelope.

Delete FCM Token

Remove an FCM token for the authenticated user, for example during logout.

DELETE /api/v1/fcm-tokens

token · string · required

FCM registration token to remove.

Response:

{
  "status": "ok"
}

This endpoint currently expects the FCM token in a JSON request body. Some HTTP clients or intermediaries strip bodies from DELETE requests, so use a client path that preserves the JSON payload. Keeping the token out of the URL also avoids encoding and length issues with long FCM tokens.

---

Related Resources

Content API

Track, album, and artist management.

Error Catalog

Social and following error codes.