> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beatpass.ca/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/search
```
Search keywords.
Comma-separated content types to search: `album`, `artist`, `playlist`, `track`, `user`. Searches all types if omitted.
Maximum results per type. Default: `3`.
**Example:**
```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/search/suggestions/artist
```
### Artist Suggestion Detail
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/search/suggestions/artist/{id}
```
### Album Search Suggestions
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/search/suggestions/album
```
### Album Suggestion Detail
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/search/suggestions/album/{id}
```
### Audio Search
Search for tracks by audio similarity.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/search/audio/{trackId}/{artistName}/{trackName}
```
***
## Genres
### List Genres
Get all available music genres.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/genres
```
### Get Genre
Get a specific genre by name, including associated content.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/genres/{name}
```
***
## Tags
### Tracks by Tag
Get tracks associated with a specific tag.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/tags/{tagName}/tracks
```
### Albums by Tag
Get albums associated with a specific tag.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/tags/{tagName}/albums
```
***
## Radio
### Get Recommendations
Get personalized music recommendations based on a seed entity (artist, track, genre, or tag).
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/radio/{type}/{id}
```
Seed type: `artist`, `track`, `genre`, or `tag`.
Seed entity ID or name.
***
## Leaderboards
### Global Leaderboard
Get the platform-wide producer leaderboard.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/leaderboards/global
```
### Genre Leaderboard
Get the leaderboard for a specific genre.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/leaderboards/genre/{genre}
```
### Rising Stars
Get the rising stars leaderboard — producers with the fastest growth.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/leaderboards/rising-stars
```
### Achievement Leaderboard
Get the leaderboard ranked by achievement count and rarity.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/leaderboards/achievements
```
### Leaderboard Stats
Get aggregate statistics for the leaderboard system.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/channel
```
### Get Channel
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/channel/{channel}
```
***
## Carousel
Featured content for homepage carousels.
### Featured Albums
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/carousel/albums
```
### Featured Tracks
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/carousel/tracks
```
### Featured Producers
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/carousel/producers
```
***
## Producer Highlights
Get highlighted producers on the platform.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-highlights
```
***
## Landing Page
### Featured Artists
Get featured artists for the landing page.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/landing/artists
```
***
## Achievement Details
Get details for a specific achievement.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/achievements/{achievementId}/details
```
***
## Related Resources
Track, album, and artist management.
XP, achievements, and analytics.