Skip to main content

Documentation Index

Fetch the complete documentation index at: https://rocks.docs.rive.wtf/llms.txt

Use this file to discover all available pages before exploring further.

Every API key is tied to one IP. To apply for a key, DM southctrl on Discord.
Use the endpoint paths below, replace the required params, and send Authorization: Bearer YOUR_API_KEY.

​
Quick Start

1

Search for a track

Pass song and artist query params to /api/spotify/search to get a full breakdown.
2

Read the tracklist

The response includes every track on the album with individual playcounts and a total.
3

Use artist and album data

Pull follower counts, monthly listeners, top cities, cover art, label, and more from the same response.
Great for music bots, stat trackers, and Discord commands that show Spotify data.
Search for a song by name and artist. Returns full track, album, and artist info in a single call.

​
Endpoint

GET /api/spotify/search

​
Query Parameters

​
song
string
required
Name of the song. Example: Hoes Mad
​
artist
string
required
Name of the artist. Example: Rich Amiri

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/spotify/search?song=Hoes+Mad&artist=Rich+Amiri" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/spotify/search?song=Hoes+Mad&artist=Rich+Amiri', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'song': 'Hoes Mad', 'artist': 'Rich Amiri'}

response = requests.get('https://rocks.rive.wtf/api/spotify/search', headers=headers, params=params)
print(response.json())

​
Example Response

{
  "track": "Hoes Mad",
  "artists": "Rich Amiri",
  "album": {
    "id": "2V3mfZot5KgRs2lZoEzkPO",
    "name": "Grit & Grace",
    "releaseDate": "2025-10-10",
    "label": "Internet Money Records / 10K Projects",
    "copyright": [
      "© 2025 Internet Money Records / 10K Projects",
      "℗ 2025 Internet Money Records / 10K Projects"
    ],
    "coverUrl": "https://i.scdn.co/image/ab67616d0000b273...",
    "totalPlays": 40926167
  },
  "artist": {
    "id": "6eUKZXaKkcviH0Ku9w2n3V",
    "name": "Rich Amiri",
    "verified": true,
    "followers": 871250,
    "monthlyListeners": 4079219,
    "profilePictureUrl": "https://i.scdn.co/image/ab6761610000e5eb...",
    "topCities": [
      { "city": "Chicago", "region": "IL", "country": "US", "numberOfListeners": 67939 },
      { "city": "Los Angeles", "region": "CA", "country": "US", "numberOfListeners": 52578 },
      { "city": "Toronto", "region": "ON", "country": "CA", "numberOfListeners": 52499 }
    ]
  },
  "tracks": [
    { "name": "Paranoid", "playcount": 13702930 },
    { "name": "In & Out", "playcount": 12013395 },
    { "name": "Hoes Mad", "playcount": 741776 }
  ]
}

​
Track

Get metadata and playcount for a single track by Spotify track ID.

​
Endpoint

GET /api/spotify/track

​
Query Parameters

​
id
string
required
Spotify track ID. Example: 4cluDES4hQEUhmXj6TXkSo

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/spotify/track?id=4cluDES4hQEUhmXj6TXkSo" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/spotify/track?id=4cluDES4hQEUhmXj6TXkSo', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'id': '4cluDES4hQEUhmXj6TXkSo'}

response = requests.get('https://rocks.rive.wtf/api/spotify/track', headers=headers, params=params)
print(response.json())

​
Example Response

{
  "id": "4cluDES4hQEUhmXj6TXkSo",
  "name": "Blinding Lights",
  "uri": "spotify:track:4cluDES4hQEUhmXj6TXkSo",
  "playcount": 5381350956,
  "durationMs": 200040,
  "explicit": false,
  "artists": [
    {
      "id": "1Xyo4u8uXC1ZmMpatF05PJ",
      "name": "The Weeknd",
      "uri": "spotify:artist:1Xyo4u8uXC1ZmMpatF05PJ"
    }
  ],
  "album": {
    "id": "4yP0hdKOZPNshxUOjY0cZj",
    "name": "After Hours",
    "uri": "spotify:album:4yP0hdKOZPNshxUOjY0cZj",
    "coverUrl": "https://i.scdn.co/image/ab67616d0000b273..."
  }
}

​
Album

Get album info and full tracklist with playcounts by album ID.

​
Endpoint

GET /api/spotify/album

​
Query Parameters

​
id
string
required
Spotify album ID. Example: 2V3mfZot5KgRs2lZoEzkPO

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/spotify/album?id=2V3mfZot5KgRs2lZoEzkPO" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/spotify/album?id=2V3mfZot5KgRs2lZoEzkPO', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'id': '2V3mfZot5KgRs2lZoEzkPO'}

response = requests.get('https://rocks.rive.wtf/api/spotify/album', headers=headers, params=params)
print(response.json())

​
Example Response

{
  "id": "2V3mfZot5KgRs2lZoEzkPO",
  "name": "Grit & Grace",
  "releaseDate": "2025-10-10",
  "label": "Internet Money Records / 10K Projects",
  "copyright": [
    "© 2025 Internet Money Records / 10K Projects",
    "℗ 2025 Internet Money Records / 10K Projects"
  ],
  "coverUrl": "https://i.scdn.co/image/ab67616d0000b273...",
  "totalPlays": 40926167,
  "tracks": [
    { "name": "So Long", "playcount": 2446700 },
    { "name": "Lights Out", "playcount": 1887978 },
    { "name": "Paranoid", "playcount": 13702930 },
    { "name": "Hoes Mad", "playcount": 741776 }
  ]
}

​
Artist

Get artist stats, follower count, monthly listeners, profile picture, and top cities by artist ID.

​
Endpoint

GET /api/spotify/artist

​
Query Parameters

​
id
string
required
Spotify artist ID. Example: 6eUKZXaKkcviH0Ku9w2n3V

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/spotify/artist?id=6eUKZXaKkcviH0Ku9w2n3V" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/spotify/artist?id=6eUKZXaKkcviH0Ku9w2n3V', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'id': '6eUKZXaKkcviH0Ku9w2n3V'}

response = requests.get('https://rocks.rive.wtf/api/spotify/artist', headers=headers, params=params)
print(response.json())

​
Example Response

{
  "id": "6eUKZXaKkcviH0Ku9w2n3V",
  "name": "Rich Amiri",
  "verified": true,
  "followers": 871250,
  "monthlyListeners": 4079219,
  "profilePictureUrl": "https://i.scdn.co/image/ab6761610000e5eb...",
  "topCities": [
    { "city": "Chicago", "region": "IL", "country": "US", "numberOfListeners": 67939 },
    { "city": "Los Angeles", "region": "CA", "country": "US", "numberOfListeners": 52578 },
    { "city": "Toronto", "region": "ON", "country": "CA", "numberOfListeners": 52499 },
    { "city": "New York City", "region": "NY", "country": "US", "numberOfListeners": 50124 },
    { "city": "London", "region": "ENG", "country": "GB", "numberOfListeners": 46888 }
  ]
}
Search for an artist by name and return full artist stats. Useful when you only have a name and not a Spotify ID.

​
Endpoint

GET /api/spotify/artist/search

​
Query Parameters

​
name
string
required
Name of the artist to search for. Example: The Weeknd

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/spotify/artist/search?name=The+Weeknd" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/spotify/artist/search?name=The+Weeknd', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'name': 'The Weeknd'}

response = requests.get('https://rocks.rive.wtf/api/spotify/artist/search', headers=headers, params=params)
print(response.json())

​
Example Response

{
  "id": "1Xyo4u8uXC1ZmMpatF05PJ",
  "name": "The Weeknd",
  "verified": true,
  "followers": 32400000,
  "monthlyListeners": 111000000,
  "profilePictureUrl": "https://i.scdn.co/image/ab6761610000e5eb...",
  "topCities": [
    { "city": "Mexico City", "region": "CDMX", "country": "MX", "numberOfListeners": 982341 },
    { "city": "Los Angeles", "region": "CA", "country": "US", "numberOfListeners": 874512 },
    { "city": "São Paulo", "region": "SP", "country": "BR", "numberOfListeners": 812034 },
    { "city": "New York City", "region": "NY", "country": "US", "numberOfListeners": 763201 },
    { "city": "London", "region": "ENG", "country": "GB", "numberOfListeners": 701488 }
  ]
}

​
Artist Top Tracks

Get an artist’s top 10 tracks with playcounts by artist ID.

​
Endpoint

GET /api/spotify/artist/top-tracks

​
Query Parameters

​
id
string
required
Spotify artist ID. Example: 1Xyo4u8uXC1ZmMpatF05PJ

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/spotify/artist/top-tracks?id=1Xyo4u8uXC1ZmMpatF05PJ" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/spotify/artist/top-tracks?id=1Xyo4u8uXC1ZmMpatF05PJ', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'id': '1Xyo4u8uXC1ZmMpatF05PJ'}

response = requests.get('https://rocks.rive.wtf/api/spotify/artist/top-tracks', headers=headers, params=params)
print(response.json())

​
Example Response

{
  "tracks": [
    {
      "id": "4cluDES4hQEUhmXj6TXkSo",
      "name": "Blinding Lights",
      "uri": "spotify:track:4cluDES4hQEUhmXj6TXkSo",
      "playcount": 5381350956,
      "durationMs": 200040,
      "explicit": false,
      "album": {
        "id": "4yP0hdKOZPNshxUOjY0cZj",
        "name": "After Hours",
        "uri": "spotify:album:4yP0hdKOZPNshxUOjY0cZj",
        "coverUrl": "https://i.scdn.co/image/ab67616d0000b273..."
      }
    },
    {
      "id": "0VjIjW4GlUZAMYd2vXMi3b",
      "name": "Starboy",
      "uri": "spotify:track:0VjIjW4GlUZAMYd2vXMi3b",
      "playcount": 4493921852,
      "durationMs": 230453,
      "explicit": true,
      "album": {
        "id": "4AdZV63mqFiqxYBhMHECRz",
        "name": "Starboy",
        "uri": "spotify:album:4AdZV63mqFiqxYBhMHECRz",
        "coverUrl": "https://i.scdn.co/image/ab67616d0000b273..."
      }
    }
  ]
}

​
Artist Discography

Get an artist’s full discography — albums, singles, and compilations — by artist ID.

​
Endpoint

GET /api/spotify/artist/discography

​
Query Parameters

​
id
string
required
Spotify artist ID. Example: 1Xyo4u8uXC1ZmMpatF05PJ

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/spotify/artist/discography?id=1Xyo4u8uXC1ZmMpatF05PJ" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/spotify/artist/discography?id=1Xyo4u8uXC1ZmMpatF05PJ', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'id': '1Xyo4u8uXC1ZmMpatF05PJ'}

response = requests.get('https://rocks.rive.wtf/api/spotify/artist/discography', headers=headers, params=params)
print(response.json())

​
Example Response

{
  "albums": [
    {
      "id": "4yP0hdKOZPNshxUOjY0cZj",
      "name": "After Hours",
      "uri": "spotify:album:4yP0hdKOZPNshxUOjY0cZj",
      "releaseDate": "2020-03-20",
      "coverUrl": "https://i.scdn.co/image/ab67616d0000b273...",
      "type": "album"
    },
    {
      "id": "4AdZV63mqFiqxYBhMHECRz",
      "name": "Starboy",
      "uri": "spotify:album:4AdZV63mqFiqxYBhMHECRz",
      "releaseDate": "2016-11-25",
      "coverUrl": "https://i.scdn.co/image/ab67616d0000b273...",
      "type": "album"
    }
  ],
  "singles": [
    {
      "id": "5vGLcdkKdEMFwAhDrMBmGz",
      "name": "São Paulo",
      "uri": "spotify:album:5vGLcdkKdEMFwAhDrMBmGz",
      "releaseDate": "2023-09-14",
      "coverUrl": "https://i.scdn.co/image/ab67616d0000b273...",
      "type": "single"
    }
  ],
  "compilations": [
    {
      "id": "7KmgMoYGAL2GQtDaBCCOhP",
      "name": "Trilogy",
      "uri": "spotify:album:7KmgMoYGAL2GQtDaBCCOhP",
      "releaseDate": "2012-11-13",
      "coverUrl": "https://i.scdn.co/image/ab67616d0000b273...",
      "type": "compilation"
    }
  ]
}

​
Prerelease

Get info about an unreleased album by Spotify prerelease ID. Returns the tracklist, release date, cover art, and any featured artists that are publicly visible before the album drops.

​
Endpoint

GET /api/spotify/prerelease

​
Query Parameters

​
id
string
required
Spotify prerelease ID. Found in prerelease URLs: open.spotify.com/prerelease/<id>. Example: 1JPh9MkYRvu1NcZ2xZler0

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/spotify/prerelease?id=1JPh9MkYRvu1NcZ2xZler0" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/spotify/prerelease?id=1JPh9MkYRvu1NcZ2xZler0', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'id': '1JPh9MkYRvu1NcZ2xZler0'}

response = requests.get('https://rocks.rive.wtf/api/spotify/prerelease', headers=headers, params=params)
print(response.json())

​
Example Response

{
  "id": "1JPh9MkYRvu1NcZ2xZler0",
  "albumId": "6O2xvUOZGywkTjQq0yM7jk",
  "name": "DONNA 2",
  "releaseDate": "2026-04-24T04:00:00Z",
  "timezone": "America/New_York",
  "coverUrl": "https://i.scdn.co/image/ab67616d0000b273...",
  "copyright": "© 2026 ETRNL RECORDS\n℗ 2026 ETRNL RECORDS",
  "trackCount": 13,
  "artists": [
    {
      "id": "0fAEWMlRd4yiJBT2usaqqc",
      "name": "Softwilly",
      "uri": "spotify:artist:0fAEWMlRd4yiJBT2usaqqc",
      "profilePictureUrl": "https://i.scdn.co/image/ab6761610000e5eb..."
    }
  ],
  "tracks": [
    {
      "name": "Track 1",
      "uri": "spotify:track:3OIeDvpkJs5OBddBkksBGW",
      "explicit": true,
      "durationMs": null,
      "playable": false,
      "artists": [
        { "id": "0fAEWMlRd4yiJBT2usaqqc", "name": "Softwilly", "uri": "spotify:artist:0fAEWMlRd4yiJBT2usaqqc" }
      ]
    },
    {
      "name": "Partyy",
      "uri": "spotify:track:0IaVAViDtNRVQfbkLnrs5h",
      "explicit": true,
      "durationMs": 167586,
      "playable": false,
      "artists": [
        { "id": "0fAEWMlRd4yiJBT2usaqqc", "name": "Softwilly", "uri": "spotify:artist:0fAEWMlRd4yiJBT2usaqqc" },
        { "id": "5RHY93srYnnr7EWPen1Oag", "name": "Jøjo", "uri": "spotify:artist:5RHY93srYnnr7EWPen1Oag" },
        { "id": "5gs6KOePAS97FunPmAheEE", "name": "LEX PAIN", "uri": "spotify:artist:5gs6KOePAS97FunPmAheEE" },
        { "id": "1FM51jrhnvagSuGSUv3kS2", "name": "Yumi", "uri": "spotify:artist:1FM51jrhnvagSuGSUv3kS2" }
      ]
    }
  ]
}
Track names are hidden (Track 1, Track 2, etc.) until the album releases. Featured artists and durations are exposed on some tracks before release.

​
Response Fields

​
Track Detail Object

FieldTypeDescription
idstringSpotify track ID
namestringTrack name
uristringSpotify URI
playcountnumberTotal play count
durationMsnumberDuration in milliseconds
explicitbooleanWhether the track is explicit
artistsobject[]List of artists
albumobjectAlbum the track belongs to

​
Album Object

FieldTypeDescription
idstringSpotify album ID
namestringAlbum name
releaseDatestringRelease date in YYYY-MM-DD format
labelstringRecord label
copyrightstring[]Copyright notices
coverUrlstringHighest resolution cover art URL
totalPlaysnumberSum of all track playcounts

​
Artist Object

FieldTypeDescription
idstringSpotify artist ID
namestringArtist name
verifiedbooleanWhether the artist is verified on Spotify
followersnumberTotal follower count
monthlyListenersnumberCurrent monthly listener count
profilePictureUrlstringHighest resolution profile picture URL
topCitiesobject[]Up to 10 cities with the most listeners

​
Discography Release Object

FieldTypeDescription
idstringSpotify album ID
namestringRelease name
uristringSpotify URI
releaseDatestringRelease date in YYYY-MM-DD format
coverUrlstringCover art URL
typestringalbum, single, or compilation

​
Prerelease Track Object

FieldTypeDescription
namestringTrack name or Track N if hidden
uristringSpotify track URI
explicitbooleanWhether the track is explicit
durationMsnumber | nullDuration in milliseconds, null if not yet revealed
playablebooleanWhether the track is currently playable
artistsobject[]Artists on the track

​
TopCity Object

FieldTypeDescription
citystringCity name
regionstringState or region code
countrystringCountry code
numberOfListenersnumberListener count in that city
Spotify periodically rotates internal API hashes. If any endpoint stops returning data, contact southctrl on Discord to get it updated.