PlaylistPilot API v1 Documentation

Response Format

All responses use a consistent JSON envelope:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "request_id": "a1b2c3d4e5f6",
    "took_ms": 342
  }
}

Errors return:

{
  "ok": false,
  "error": {
    "code": "INVALID_QUERY",
    "message": "Human-readable error description."
  }
}

Rate Limiting

The API uses IP-based rate limiting. Limits are communicated via response headers:

`X-RateLimit-Limit`	Maximum requests per window (30)
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Window`	Window duration in seconds (60)
`Retry-After`	Seconds to wait (only on 429 responses)

GET /api/v1/search

Search for tracks by query, artist, or genre. Uses AI-powered intent detection to understand natural language queries.

Parameters

Param	Type	Required	Description
`q`	string	Yes*	Search query (e.g. "workout playlist", "album thriller", "aktuelle hits")
`artists`	string	No	Comma-separated artist names
`genre`	string	No	Genre filter (use `/genres` for options)
`limit`	int	No	Max results, 1-50 (default: 25)

* Either q or artists must be provided.

Example

curl "https://www.playlistpilot.eu/api/v1/search?q=workout+playlist&genre=pop&limit=10"

// JavaScript
const res = await fetch('/api/v1/search?q=aktuelle+hits&limit=5');
const { data } = await res.json();

GET /api/v1/genres

Returns all available music genres.

Example

curl "https://www.playlistpilot.eu/api/v1/genres"

// Response
{
  "ok": true,
  "data": {
    "total": 23,
    "genres": [
      { "id": 132, "name": "Pop" },
      { "id": 152, "name": "Rock" },
      ...
    ]
  }
}

GET /api/v1/trending

Returns the most popular search terms from other users.

Parameters

Param	Type	Default	Description
`hours`	int	24	Lookback window, 1-168
`limit`	int	10	Max results, 1-50

Example

curl "https://www.playlistpilot.eu/api/v1/trending?hours=48&limit=5"

GET /api/v1/playlist/{slug}

Retrieve a shared playlist by its URL slug.

Example

curl "https://www.playlistpilot.eu/api/v1/playlist/workout-energy-power"

// Response
{
  "ok": true,
  "data": {
    "slug": "workout-energy-power",
    "title": "Workout Energy Power",
    "total_tracks": 12,
    "tracks": [
      { "id": 123456, "title": "Eye of the Tiger", "artist": "Survivor", ... }
    ]
  }
}

POST /api/v1/suggest

Get AI-powered song suggestions based on a list of tracks you enjoy. Powered by OpenAI and Deezer.

Request Body (JSON)

{
  "tracks": [
    { "title": "Blinding Lights", "artist": "The Weeknd" },
    { "title": "Levitating", "artist": "Dua Lipa" },
    { "title": "Peaches", "artist": "Justin Bieber" }
  ]
}

Example

curl -X POST "https://www.playlistpilot.eu/api/v1/suggest" \
  -H "Content-Type: application/json" \
  -d '{"tracks": [{"title": "Bohemian Rhapsody", "artist": "Queen"}]}'

Max 20 input tracks. Returns up to 15 suggestions.

Built with ♥ by SPCast

← Back to PlaylistPilot