Rippl3 API Documentation

Discover, search, and recommend songs with AI-powered embeddings. Public endpoints for seamless integration.

Introduction

The Rippl3 API provides powerful tools for music discovery and recommendation using advanced audio embeddings. All endpoints are public and rate-limited for anonymous users. Premium users (via JWT) get higher limits.

Base URL

https://api.rippl3.net/v1/public/

Authentication

Optional JWT Bearer token for premium features.

Rate Limits

Anon: 100 req/hour. Premium: 10,000 req/hour.

🎵 Get Similar Songs

GET/recommendations/similar/song_id/

Retrieve songs similar to the given song ID using cosine similarity on audio embeddings.

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Max songs to return (default: 10, max: 1000 for premium)
min_similarity	float	No	Min similarity threshold (default: 0)

Response

{
  "recommended_songs": [
    {
      "id": "123",
      "title": "Song Title",
      "artist": "Artist Name",
      "cover_art": "https://...",
      "permalink_url": "https://soundcloud.com/..."
    }
  ]
}

🔍 Search Songs & Playlists

GET/search/

Full-text search across songs and public playlists using trigram similarity.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query
page	integer	No	Page number (default: 1, size: 20)

Response

{
  "results": [
    {
      "type": "song",
      "data": { "id": "123", "title": "Song", "artist": "Artist" }
    },
    {
      "type": "playlist",
      "data": { "id": "456", "name": "Playlist Name" }
    }
  ],
  "next": "/api/v1/public/search/?q=query&page=2",
  "previous": null
}

⚖️ Pairwise Similarity

GET/similarity-pair/

Compute cosine similarity between two songs (0-1 scale).

Query Parameters

Parameter	Type	Required	Description
song1	string	Yes	First song ID
song2	string	Yes	Second song ID

Response

{
  "similarity": 0.85
}