Recently played
the purple life API
the purple life is a free music streaming platform for original songs by the purple life — not a multi-artist marketplace. Public REST API reference for health checks, catalog search, radio status, OpenAPI, and Markdown exports. Prefer Accept: text/markdown (or .md URLs) for lyrics and backstories.
Machine-readable schema: /openapi.json · agent.txt · llms.txt · contact
Getting started · zero-auth public API · path versioning under /api/v1
Authentication
None required. Documented public /api/v1 routes do not use API keys or Authorization headers. Verify live access with GET/api/v1/health.
Versioning and deprecation
Public product JSON uses the /api/v1 path prefix. Breaking changes ship under a new path version. Deprecated operations are marked in OpenAPI, called out on their docs pages, and may send Deprecation / Sunset response headers.
Rate limiting
Public /api/v1 routes are rate-limited per client IP and endpoint scope. Limits are intentionally modest (often on the order of tens of requests per minute for public reads).
Over the limit, the API returns HTTP 429 with JSON { "error": { "code": "rate_limited", "message", "hint?" } } and a Retry-After header (seconds). Clients and agents must honor Retry-After and must not retry sooner.
Endpoints
Health
- GET /api/v1/health
Public process health. version is the build SHA, or unknown when it is not set.
Search
- GET /api/v1/search
Public catalog search.
- GET /api/v1/search/suggest
Short public search suggestions. limit max is 20.
Radio
- GET /api/v1/radio/clock
Returns the server clock used to sync the radio player.
- GET /api/v1/radio/listeners
Active radio listener count only (
{ "number": <count> }). Use this when you need the count without the fuller radio sync payload from GET/api/v1/radio/status. - GET /api/v1/radio/now-playing
Returns the track currently on the radio clock.
- POST /api/v1/radio/presence
Updates radio listener presence for a client session id.
- GET /api/v1/radio/status
Radio sync payload (track timing, seed, and listenerCount). Prefer GET
/api/v1/radio/listenerswhen you only need the active listener count. - GET /api/v1/radio/tune-in
Full radio sync payload for a new listener.
Catalog
- GET /api/openapi.json
OpenAPI 3.1 document for public agent-facing REST endpoints (alias of /openapi.json).
- GET /api/v1/albums/:handle/download
Redirects to the public album zip on the CDN.
- GET /api/v1/double-singles/:handle/download
Redirects to the public double-single zip on the CDN.
- GET /api/v1/eps/:handle/download
Redirects to the public EP zip on the CDN.
- GET /api/v1/leaderboard
Public leaderboard page. section is required.
- POST /api/v1/push/subscribe
Stores a web push subscription. Rate limited.
- POST /api/v1/push/unsubscribe
Removes a web push subscription.
- GET /api/v1/recently-played
Recently qualified public streams.
- GET /api/v1/songs/:handle/audio
Redirects to the public streaming audio URL.
- GET /api/v1/songs/:handle/download
Redirects to the public song download on the CDN.