Rippl3 API Documentation

Discover, search, and recommend songs with AI-powered embeddings.

Getting Started

The Rippl3 API provides powerful tools for music discovery and recommendation using advanced audio embeddings. All endpoints are public with tiered rate limits. Authentication is optional but unlocks higher limits and premium features.

Base URL

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

Authentication

Optional — required for higher rate limits and premium features.

Authorization: Bearer <your_api_key>

Permanent API key (recommended): Never expires — ideal for scripts and apps.
Short-lived JWT tokens also work but expire in ~15 minutes.

Logged-in users can generate and manage their permanent API key in the next section.

Rate Limits & API Keys

Rate Limits

  • Anonymous: 20 requests per hour(your current tier)
  • Registered (Free): 1,000 requests per day
  • Premium: Unlimited(upgrade)

Endpoints

Get Similar Songs

GET/recommendations/similar/{song_id}/

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

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoMax songs to return (default: 10; max 10 for free/anon, max 1000 for premium)
min_similarityfloatNoMinimum similarity threshold (default: 0.0; only premium users can set > 0)

Response

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

Examples

Basic (no auth)

curl "https://api.rippl3.net/api/v1/public/recommendations/similar/123/"

Authenticated (higher limits + premium filters)

curl -H "Authorization: Bearer <your_api_key>" \
  "https://api.rippl3.net/api/v1/public/recommendations/similar/123/?limit=500&min_similarity=0.8"

Pairwise Similarity

GET/similarity-pair/

Compute cosine similarity (0–1) between any two songs — by ID or search string.

Query Parameters

ParameterTypeRequiredDescription
song1stringYesSong ID or search query
song2stringYesSong ID or search query

Examples

By ID

curl "https://api.rippl3.net/api/v1/public/similarity-pair/?song1=123&song2=456"

By search string

curl "https://api.rippl3.net/api/v1/public/similarity-pair/?song1=Never+Gonna+Give+You+Up&song2=Careless+Whisper"

Authenticated

curl -H "Authorization: Bearer <your_api_key>" \
  "https://api.rippl3.net/api/v1/public/similarity-pair/?song1=123&song2=456"

Submit Similarity Rating (Help Improve the Model)

POST/rate-pair/

Submit a human similarity rating (1–10) for any song pair. This data helps train and improve the recommendation model.

Request Body (JSON)

{
  "song1_id": 123,
  "song2_id": 456,
  "rating": 8   // integer 1–10
}

Example

curl -X POST "https://api.rippl3.net/api/v1/public/rate-pair/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_key>" \
  -d '{"song1_id": 123, "song2_id": 456, "rating": 8}'

Authentication optional (same rate limits apply). Higher-rated pairs influence future recommendations.