Content Management API

Manage tracks, albums, artists, playlists, Backstage producer requests, audio fingerprinting, audio recon, and cover art on BeatPass.

Overview

The Content Management API provides full CRUD operations for all content types on BeatPass — tracks, albums, artists, playlists, lyrics, producer access requests, and supporting features like audio fingerprinting, Audio Recon, and cover art generation.

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

Authentication: Read operations use optional auth (enhanced data when logged in). Write operations require authentication.

---

Tracks

List Tracks

GET /api/v1/tracks

Public endpoint. Returns enhanced data (purchase status, like status) when authenticated.

Get Track

GET /api/v1/tracks/{track}

Create Track

Upload a new track. Requires authentication.

POST /api/v1/tracks

Update Track

PUT /api/v1/tracks/{track}

Delete Track(s)

DELETE /api/v1/tracks/{ids}

ids · string · required

Comma-separated track IDs to delete.

Download Track

GET /api/v1/tracks/{track}/download

Get Waveform Data

GET /api/v1/tracks/{track}/wave

Batch Waveform Data

POST /api/v1/tracks/wave-batch

Extract Metadata

Extract metadata from an uploaded audio file entry.

POST /api/v1/tracks/{fileEntry}/extract-metadata

Log Track Play

Record a play event for a track.

POST /api/v1/tracks/{track}/plays

Update Play Duration

Update the listen duration of an active playback.

POST /api/v1/tracks/plays/{track}/update-duration

Get Engagement Metrics

GET /api/v1/tracks/{track}/engagement-metrics

Get Producer Analytics

GET /api/v1/tracks/{track}/producer-analytics

---

Track Upload Flow

1. Upload Audio File

   Upload the audio file via the file upload system to get a fileEntry ID.

2. Extract Metadata

   Call POST /tracks/{fileEntry}/extract-metadata to parse BPM, key, duration, etc.

3. Create Track

   Call POST /tracks with metadata (title, genre, tags, BPM, etc.) and the file entry reference.

4. Audio Fingerprinting

   The system automatically generates an audio fingerprint for duplicate detection.

5. Published

   Track is published and available on the platform.

---

Albums

List Albums

GET /api/v1/albums

Get Album

GET /api/v1/albums/{album}

Create Album

POST /api/v1/albums

Update Album

PUT /api/v1/albums/{album}

Delete Album(s)

DELETE /api/v1/albums/{ids}

Album Producer Analytics

GET /api/v1/albums/{album}/producer-analytics

---

Artists

List Artists

GET /api/v1/artists

Get Artist

GET /api/v1/artists/{artist}

Get Artist’s Tracks

GET /api/v1/artists/{artist}/tracks

Get Artist’s Albums

GET /api/v1/artists/{artist}/albums

Producer Analytics

GET /api/v1/artists/{artist}/producer-analytics

Downloads Analytics

GET /api/v1/artists/{artist}/downloads-analytics

Producer Achievements

GET /api/v1/artists/{artist}/producer-achievements

Check Ownership

Check if the authenticated user owns this artist profile.

GET /api/v1/artists/{artist}/check-ownership

---

Producer Program Requests (Backstage)

Producer/artist profile requests are managed through the Backstage request flow.

Get Submission Status

Check whether the authenticated user can submit a new producer request.

GET /api/v1/backstage-request/submission-status

Response (can submit):

{
  "can_submit": true,
  "block_reason": null,
  "message": null,
  "contact_url": null,
  "blocking_request_id": null
}

Response (blocked):

{
  "can_submit": false,
  "block_reason": "revoked",
  "message": "Your producer access was revoked. To appeal, contact support at /contact so admins can review your request for reinstatement.",
  "contact_url": "/contact",
  "blocking_request_id": 412
}

Create Backstage Request

Submit a new producer request.

POST /api/v1/backstage-request

type · string · required

Request type. Supported values: become-artist, verify-artist, claim-artist.

artist_name · string · required

Display name for the producer/artist request.

artist_id · integer | string

Artist reference for claim/verification flows. Client may pass CURRENT_USER in create flow.

data · object · required

Request payload object (for example: first_name, last_name, beats_url, role, company, optional supporting fields).

Submission Guard Policy

The create endpoint enforces a global per-user guard across all request types:

Existing status	Can submit new request?	Behavior
pending	No	409 Conflict with error_code: backstage_request_pending
revoked	No	409 Conflict with error_code: backstage_request_revoked
denied	Yes	Submission allowed
approved	Yes	Submission allowed

If both pending and revoked exist, pending takes precedence for messaging and error code.

Conflict Responses (Create)

{
  "message": "Your application is already under review. Please wait for the decision email before submitting another request.",
  "error_code": "backstage_request_pending"
}

{
  "message": "Your producer access was revoked. To appeal, contact support at /contact so admins can review your request for reinstatement.",
  "error_code": "backstage_request_revoked"
}

---

Artist Credits

Professional portfolio credits (similar to Spotify credits). Allows artists to showcase their work on external releases.

List Credits

GET /api/v1/artists/{artist}/credits

Add Credit

POST /api/v1/artists/{artist}/credits

Add Album Credit

POST /api/v1/artists/{artist}/credits/album

Update Credit

PUT /api/v1/artists/{artist}/credits/{credit}

Delete Credit

DELETE /api/v1/artists/{artist}/credits/{credit}

Reorder Credits

POST /api/v1/artists/{artist}/credits/reorder

Spotify Search (for Credits)

Search Spotify catalog to link credits to releases.

GET /api/v1/credits/spotify-search

Get Spotify Album

GET /api/v1/credits/spotify-album

Credit Roles (Public)

Get the list of available credit roles (e.g., Producer, Engineer, Songwriter).

GET /api/v1/credits/roles

---

Track Pinning

Pin a featured track to the top of an artist’s profile.

Pin Track

POST /api/v1/artists/{artistId}/tracks/{trackId}/pin

Unpin Track

POST /api/v1/artists/{artistId}/tracks/{trackId}/unpin

Get Pinned Track

GET /api/v1/artists/{artistId}/pinned-track

---

Playlists

List Playlists

GET /api/v1/playlists

Get Playlist

GET /api/v1/playlists/{id}

Create Playlist

POST /api/v1/playlists

Update Playlist

PUT /api/v1/playlists/{playlist}

Delete Playlist(s)

DELETE /api/v1/playlists/{ids}

Follow Playlist

POST /api/v1/playlists/{id}/follow

Unfollow Playlist

POST /api/v1/playlists/{id}/unfollow

Get Playlist Tracks

GET /api/v1/playlists/{id}/tracks

Add Tracks

POST /api/v1/playlists/{playlist}/tracks/add

Remove Tracks

POST /api/v1/playlists/{playlist}/tracks/remove

Reorder Tracks

POST /api/v1/playlists/{playlist}/tracks/order

---

Playlist Collaboration

Invite Collaborator

POST /api/v1/playlists/{playlist}/invite

Accept Invitation

POST /api/v1/playlists/{playlist}/accept-invite

Decline Invitation

POST /api/v1/playlists/{playlist}/decline-invite

Remove Editor

POST /api/v1/playlists/{playlist}/remove-editor

Collaborative playlists support up to 10 editors. Invitations expire after 7 days. A 24-hour cooldown applies between re-invites.

---

Lyrics

List Lyrics

GET /api/v1/lyrics

Get Track Lyrics

GET /api/v1/tracks/{id}/lyrics

Create Lyrics

POST /api/v1/lyrics

Update Lyrics

PUT /api/v1/lyrics/{id}

Delete Lyrics

DELETE /api/v1/lyrics/{ids}

---

Audio Fingerprinting

Detect duplicate audio content using acoustic fingerprints.

Generate Fingerprint

POST /api/v1/tracks/{track}/fingerprint

Check Fingerprint Status

GET /api/v1/tracks/{track}/fingerprint/status

Check Duplicates

Check uploaded audio against existing fingerprints.

POST /api/v1/tracks/check-duplicates

Retry Failed Fingerprint

POST /api/v1/fingerprints/{fingerprint}/retry

---

Audio Recon

Audio Recon detects songs on streaming platforms (Spotify, YouTube, Deezer) that share audio characteristics with tracks on BeatPass. Results are available to the track’s credited producers and admins.

Audio Recon scanning runs on a scheduled background job (daily), with tracks rescanned on a rolling cycle (target around 30 days).

Get Audio Recon Matches

Retrieve detected audio similarities for a specific track. Requires authentication. Only accessible by producers credited on the track.

GET /api/v1/tracks/{track}/placements

track · integer · required

The track ID to retrieve Audio Recon matches for.

Response:

{
  "placements": [
    {
      "id": 42,
      "title": "Song Title",
      "artist_name": "Artist Name",
      "album_name": "Album Name",
      "release_date": "2025-06-15",
      "confidence_score": 95,
      "spotify_url": "https://open.spotify.com/track/...",
      "youtube_url": "https://youtube.com/watch?v=...",
      "deezer_url": "https://deezer.com/track/...",
      "created_at": "2026-02-20T12:00:00+00:00"
    }
  ],
  "scan_status": "complete",
  "scanned_at": "2026-02-26T02:15:00+00:00",
  "total_count": 1,
  "artist_verified": true
}

placements · array

Array of detected audio similarities, sorted by confidence score (highest first).

placements[].confidence_score · integer

Audio similarity percentage. The endpoint returns high-confidence matches only (current display threshold is 90+).

placements[].spotify_url · string | null

Direct link to the matched song on Spotify, if available.

placements[].youtube_url · string | null

Direct link to the matched song on YouTube, if available.

placements[].deezer_url · string | null

Direct link to the matched song on Deezer, if available.

total_count · integer

Total number of matches returned.

scan_status · string | null

Current scan state for the track (processing, complete, no_results, failed, or null before first scan).

scanned_at · string | null

ISO timestamp of the latest scan attempt.

artist_verified · boolean

Whether the track’s primary artist has a verified profile. Scanning requires a verified artist.

Audio Recon detects audio similarity, not confirmed placements. A match could indicate your beat was used, a shared sample, or coincidence. Always verify by listening.

Error	Code	Cause
Unauthenticated	401	No valid Bearer token provided
Forbidden	403	You are not a credited producer on this track
Not Found	404	Track does not exist

---

Cover Art

List Templates

GET /api/v1/cover-art/templates

Get Template

GET /api/v1/cover-art/templates/{template}

Preview Cover Art

Generate a preview with a template and custom parameters.

POST /api/v1/cover-art/preview

Get Matching Templates

Get templates that match specific criteria (genre, mood, etc.).

GET /api/v1/cover-art/matching-templates

---

Related Resources

Commerce & Licensing

Purchase flow and license certificates for tracks.

Search & Discovery

Search, genres, tags, and radio recommendations.