Search & Discovery API

Full-text search, genre and tag filtering, radio recommendations, and leaderboard endpoints.

Overview

The Search & Discovery API provides content discovery features — full-text search across all content types, genre and tag browsing, personalized radio recommendations, and platform-wide leaderboards.

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

Authentication: All discovery endpoints use optional auth. Authenticated users get personalized results and enhanced data.

---

Search

Full-Text Search

Search across albums, artists, playlists, tracks, and users.

GET /api/v1/search

query · string · required

Search keywords.

types · string

Comma-separated content types to search: album, artist, playlist, track, user. Searches all types if omitted.

limit · integer

Maximum results per type. Default: 3.

Example:

curl "https://open.beatpass.ca/api/v1/search?query=lofi&types=track,artist&limit=5" \
  -H "Accept: application/json"

---

Artist Search Suggestions

Get autocomplete suggestions for artists.

GET /api/v1/search/suggestions/artist

Artist Suggestion Detail

GET /api/v1/search/suggestions/artist/{id}

Album Search Suggestions

GET /api/v1/search/suggestions/album

Album Suggestion Detail

GET /api/v1/search/suggestions/album/{id}

Audio Search

Search for tracks by audio similarity.

GET /api/v1/search/audio/{trackId}/{artistName}/{trackName}

---

Genres

List Genres

Get all available music genres.

GET /api/v1/genres

Get Genre

Get a specific genre by name, including associated content.

GET /api/v1/genres/{name}

---

Tags

Tracks by Tag

Get tracks associated with a specific tag.

GET /api/v1/tags/{tagName}/tracks

Albums by Tag

Get albums associated with a specific tag.

GET /api/v1/tags/{tagName}/albums

---

Radio

Get Recommendations

Get personalized music recommendations based on a seed entity (artist, track, genre, or tag).

GET /api/v1/radio/{type}/{id}

type · string · required

Seed type: artist, track, genre, or tag.

id · string · required

Seed entity ID or name.

---

Leaderboards

Global Leaderboard

Get the platform-wide producer leaderboard.

GET /api/v1/leaderboards/global

Genre Leaderboard

Get the leaderboard for a specific genre.

GET /api/v1/leaderboards/genre/{genre}

Rising Stars

Get the rising stars leaderboard — producers with the fastest growth.

GET /api/v1/leaderboards/rising-stars

Achievement Leaderboard

Get the leaderboard ranked by achievement count and rarity.

GET /api/v1/leaderboards/achievements

Leaderboard Stats

Get aggregate statistics for the leaderboard system.

GET /api/v1/leaderboard/stats

Leaderboard data is cached with a 5-minute TTL. Polling more frequently than every 30 seconds is unnecessary and wastes your rate limit quota.

---

Channels

Channels are curated content feeds on the platform.

List Channels

GET /api/v1/channel

Get Channel

GET /api/v1/channel/{channel}

---

Carousel

Featured content for homepage carousels.

Featured Albums

GET /api/v1/carousel/albums

Featured Tracks

GET /api/v1/carousel/tracks

Featured Producers

GET /api/v1/carousel/producers

---

Producer Highlights

Get highlighted producers on the platform.

GET /api/v1/producer-highlights

---

Landing Page

Featured Artists

Get featured artists for the landing page.

GET /api/v1/landing/artists

---

Achievement Details

Get details for a specific achievement.

GET /api/v1/achievements/{achievementId}/details

---

Related Resources

Content API

Track, album, and artist management.

Producer Intelligence

XP, achievements, and analytics.