◆ v1.0 · REST API

Playlist Pilot API

Programmatic access to a curated playlist network — AI matching, pitch generation, and bot detection.

No API key yet? Request access →

🔑 API Key

No key

Overview

2M+

Max Followers

Endpoints

Pitch & Matching

REST

JSON API

All endpoints return JSON. The base URL for all requests is:

https://playlistpilotapp.com/api/v1

Authentication

All endpoints require a Bearer token in the Authorization header.

Add this header to every request:

Authorization: Bearer your_api_key_here

Example with curl

curl -X GET \
  https://playlistpilotapp.com/api/v1/genres \
  -H "Authorization: Bearer your_api_key_here"

Rate Limits

Rate limits are per API key, per endpoint, on a sliding 1-hour window. Exceeding limits returns 429 RateLimitExceeded.

Endpoint	Limit / hour	Notes
POST /match	60	Scores against our curator network
POST /expand-artists	20	AI-powered — higher latency
GET /playlists/{id}	120	Live fetch — works for any public playlist
GET /playlists/{id}/similar	60	Requires ID from match results
GET /playlists/{id}/contacts	30	Always live — fresh scrape + AI extraction
GET /playlists/{id}/bot-check	20	Live analysis
POST /playlists/{id}/pitch	30	AI-powered — higher latency
GET /genres	120	Cached in-memory

Error Reference

HTTP Code	Error Type	Meaning
200	—	Success
400	BadRequest	Missing or invalid request parameters
401	Unauthorized	Missing, invalid, or revoked API key
404	NotFound	Playlist ID not found in database
429	RateLimitExceeded	Hourly rate limit reached for this endpoint
500	InternalError	Server-side failure — try again shortly

Matching

POST /api/v1/match 60/hr

AI-powered playlist matching. Returns the top playlists from the curator network ranked by genre and artist overlap.

Field	Type	Description	Required
genres	string[]	Song genres (e.g. ["indie pop", "bedroom pop"])	required*
artists	string[]	Artist names for audience overlap	required*
similar_artists	string[]	Similar/comparable artists	optional
follower_min	integer	Minimum playlist followers (default: 50)	optional
follower_max	integer	Maximum playlist followers (default: 2,027,415)	optional
limit	integer	Number of results, max 50 (default: 10)	optional

* At least one of genres or artists is required.

Request

{ "genres": ["indie pop"], "artists": ["Phoebe Bridgers"], "follower_min": 1000, "limit": 5 }

Response

{ "success": true, "total_found": 247, "returned": 5, "matches": [{ "playlist_id": "...", "playlist_name": "Indie Vibes", "followers": 42500, "match_score": 94.2, "spotify_url": "https://open.spotify.com/playlist/..." }] }

Parameters

genres (comma-separated)

artists (comma-separated)

similar_artists (comma-separated)

follower_min

follower_max

limit

Response

⚡Click "Send Request" to test this endpoint

POST /api/v1/expand-artists 20/hr

AI artist intelligence. Provide a comma-separated string or an array of artist names and receive inferred genres and tiered similar artists — optimised for use as genres and similar_artists inputs to the match endpoint.

Request

{ "artists": "Billie Eilish, Lorde" }
// or
{ "artists": ["Billie Eilish", "Lorde"] }

Response

{
  "success": true,
  "genres": ["alt pop", "dark pop", "indie pop"],
  "tier1_artists": ["Olivia Rodrigo", "Gracie Abrams", ...],
  "tier2_artists": ["Halsey", "Charli XCX", ...]
}

Parameters

artists *

Response

⚡Click "Send Request" to test this endpoint

Playlist Data

GET /api/v1/playlists/{playlist_id} 120/hr

Full metadata for a single playlist, fetched live. Works for any public playlist ID — not limited to our curator network.

Path Parameters

playlist_id *

Response

⚡Click "Send Request" to test this endpoint

GET /api/v1/playlists/{playlist_id}/similar 60/hr

Returns playlists most similar to the specified playlist, based on genre and artist overlap.

Note: Only works with playlist IDs returned by the POST /match endpoint. The playlist must exist in our curator network database.

Parameters

playlist_id *

limit

Response

⚡Click "Send Request" to test this endpoint

GET /api/v1/genres 120/hr

All unique genres present in our curator network, sorted by playlist count. Returns a flat array of strings. Useful for building genre pickers or validating inputs before a match call. Response is cached in-memory.

Request

GET /api/v1/genres

Response

{ "success": true, "genres": ["hip hop", "indie pop", "r&b", ...] }

No Parameters

Response

⚡Click "Send Request" to test this endpoint

Contacts

Extract verified curator contact details — email addresses, Instagram handles, Twitter/X profiles, TikTok accounts, and personal websites. Results are cached in the Playlist Pilot database, so repeat lookups are instant.

GET /api/v1/playlists/{id}/contacts 30/hr

Fetches the curator's contact info fresh on every request — no stale cache. Any email, Instagram, Twitter/X, TikTok, or website is extracted and returned. Results are written to cache after extraction but never read from it, so you always get the latest data. The response includes a contact_url ready to open directly.

Field	Type	Description
contact_type	string	`email`, `instagram`, `twitter`, `tiktok`, `website`, or `other`
contact_raw	string	Raw value — just the username (no URL prefix) for social platforms, full email address, or URL for websites
contact_display	string	Human-readable label, e.g. `Instagram: @indievibes`
contact_url	string	Ready-to-use URL: `mailto:x@y.com`, `https://www.instagram.com/user`, etc.

Request

GET /api/v1/playlists/37i9dQZF1DXcBWIGoYBM5M/contacts

Response

{
  "success": true,
  "playlist_id": "37i9dQZF1DXcBWIGoYBM5M",
  "spotify_url": "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M",
  "contact_found": true,
  "contact": {
    "contact_type": "instagram",
    "contact_raw": "indievibes",
    "contact_display": "Instagram: @indievibes",
    "contact_url": "https://www.instagram.com/indievibes"
  }
}

Parameters

playlist_id *

Response

⚡Click "Send Request" to test this endpoint

Trust & Safety

GET /api/v1/playlists/{playlist_id}/bot-check 20/hr

Live bot-detection analysis. Returns a trust score (0–100), a badge, and the individual signals that contributed to the result.

Badge values: Trusted (score ≥ 70) · Caution (40–69) · Risky (below 40)

Path Parameters

playlist_id *

Response

⚡Click "Send Request" to test this endpoint

Pitch Generation

POST /api/v1/playlists/{playlist_id}/pitch 30/hr

Generate a personalised AI pitch for a specific playlist, contextualised using the playlist's genre profile and your song metadata.

Field	Type	Description	Required
artist_name	string	Artist or band name	required
song_name	string	Song/track title	required
song_url	string	Streaming link for the track	optional
genres	string[]	Song genres	optional
similar_artists	string[]	Comparable artists	optional
tone	string	`professional` · `casual` · `enthusiastic`	optional
mood	string	`respectful` · `bold` · `humble`	optional
language	string	Output language (default: english)	optional
custom_instructions	string	Freeform instructions woven into the pitch — e.g. "mention we have 50k monthly listeners" or "keep it under 100 words"	optional

Parameters

playlist_id *

artist_name *

song_name *

song_url

genres (comma-separated)

similar_artists (comma-separated)

tone

mood

custom_instructions (optional)

Response

⚡Click "Send Request" to test this endpoint

Internal · Owner Only

Not available to partner accounts. Requires the private owner key, not a partner API key. Used by our own marketing pipeline.

GET /api/v1/segments 60/hr

Returns the most recent users bucketed into lifecycle segments (max 50 groups) so a marketing pipeline can send one tailored email per group. Only opted-in, active users are included — opted-out and disabled accounts are never returned. Each user includes a signed unsubscribe_url: embed it in the email footer so recipients can opt out in one click. Once they do, they drop out of every future response automatically.

Field	Type	Description	Required
limit	integer	Number of most-recent users to scan, max 5000 (default: 1000)	optional

Request

GET /api/v1/segments?limit=1000
Authorization: Bearer <owner_key>

Response

{ "success": true, "generated_at": "2026-06-26T12:00:00+00:00", "total_users": 1000, "group_count": 8, "max_groups": 50, "groups": [ { "key": "signed_up_idle", "label": "Signed up, did nothing", "description": "...", "count": 240, "users": [ { "email": "a@b.com", "first_name": "Alex", "plan": "free", "days_since_signup": 3, "unsubscribe_url": "https://playlistpilotapp.com/unsubscribe?uid=42&token=..." } ] } ] }

Playlist Pilot Partner API · For access requests or support, contact the Playlist Pilot team.