Skip to content

Developers

Tunova Public API

Build players, widgets, dashboards and bots on top of the Tunova catalog — songs, artists, albums, charts, search, playlists and play events — over a simple REST API with scoped personal access tokens.

Base URL

https://bongotracks.com/api/v1

All responses are JSON with a { "data": … } envelope; errors use { "error": { "code", "message" } } and honest HTTP status codes.

Quick start

1.Create a token in Account → Security → API tokens. Give it a name (e.g. “my app”) and pick the scopes it needs. The token is shown once — copy it somewhere safe.

2.Send it as a bearer header:

curl "https://bongotracks.com/api/v1/auth/me" \
  -H "Authorization: Bearer afro_YOUR_TOKEN"

3.Catalog endpoints are open (no token needed); everything personal requires one:

curl "https://bongotracks.com/api/v1/catalog/artists/juma-jux?top=5"

# → { "data": { "artist": { "name": "Juma Jux", … }, "songs": […] } }

Scopes

Tokens are privilege-limited: no scope ever grants admin access.

catalog:readBrowse charts, search, songs, artists and playlists
library:readRead your playlists, recommendations and download grants
library:writeRecord play events (scrobble) and manage your playlists
account:readRead your profile and subscription status

Endpoints

Catalog — open to everyone

GET/catalog/songs/{id}open

One approved song (metadata + signed stream URL).

GET/catalog/artists/{slug}?top=10open

Artist profile, top songs and albums.

GET/catalog/albums/{artistSlug}/{albumSlug}open

Album with its track list.

GET/catalog/new-releases?limit=20open

Newest approved releases.

GET/catalog/genresopen

All genres.

GET/catalog/playlists/{slug}open

Featured playlist with tracks.

GET/catalog/videosopen

Music videos.

GET/charts?window=7dopen

Top charts (windows: 24h, 7d, 30d, all-time).

GET/search?q=&type=open

Search songs, artists, albums and playlists.

Personal — Bearer token required

GET/auth/meaccount:read

Your profile, roles and subscription status.

GET/playlistslibrary:read

Your playlists.

POST/playlistslibrary:write

Create a playlist.

PATCH/playlists/{id}library:write

Rename / edit a playlist.

POST/play-eventslibrary:write

Record a play event (scrobble) — feeds charts and recommendations.

GET/recommendationslibrary:read

Personalized recommendations.

Rate limits

  • 600 requests/minute per API token (on top of per-route limits) — exceed it and you get 429 RATE_LIMITED.
  • 60 requests/minute per IP on open catalog endpoints.
  • Catalog responses carry a strong ETag — send If-None-Match to get cheap 304s.

Errors

  • 401 INVALID_TOKEN — malformed, revoked or deleted token.
  • 401 TOKEN_EXPIRED — the token's expiry date has passed.
  • 403 FORBIDDEN — valid token, but it lacks the scope the endpoint needs.
  • 429 RATE_LIMITED — slow down, retry after the window.

🔑 Tokens are for mobile apps, scripts and servers. They authenticate without cookies, can be revoked anytime from Account → Security, and never unlock admin endpoints. Tokens are shown once at creation — we store only a hash, so a lost token must be replaced.