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 path below, replace the required params, and send Authorization: Bearer YOUR_API_KEY.

​
Quick Start

1

Prepare your audio file

Make sure your file is a supported format (.mp3, .mp4, .m4a, .wav, .ogg, .flac, .aac, .webm) and under 10 MB.
2

Choose an identification method

Upload a file directly via POST /api/shazam/identify or pass a server-side file path via GET /api/shazam/identify?path=.
3

Read the result

Check matched in the response. If true, the track object contains the title, artist, genre, album, and more.
Great for music recognition bots, Discord commands, and audio tagging tools.

​
Identify via File Upload

Upload an audio or video file and identify the song.

​
Endpoint

POST /api/shazam/identify

​
Body

​
file
file
required
Audio or video file sent as multipart/form-data.

​
Example Request

cURL
curl -X POST "https://rocks.rive.wtf/api/shazam/identify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/song.mp3"
JavaScript
const form = new FormData();
form.append('file', fs.createReadStream('./song.mp3'));

const response = await fetch('https://rocks.rive.wtf/api/shazam/identify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: form
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}

with open('song.mp3', 'rb') as f:
    response = requests.post(
        'https://rocks.rive.wtf/api/shazam/identify',
        headers=headers,
        files={'file': f}
    )
print(response.json())

​
Identify via File Path

Identify a song using a file that already exists on the server.

​
Endpoint

GET /api/shazam/identify

​
Query Parameters

​
path
string
required
Absolute path to the audio/video file on the server (e.g. /srv/audio/song.mp3).

​
Example Request

cURL
curl -X GET "https://rocks.rive.wtf/api/shazam/identify?path=/srv/audio/song.mp3" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/shazam/identify?path=/srv/audio/song.mp3', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'path': '/srv/audio/song.mp3'}

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

​
Example Response

​
Matched

{
  "matched": true,
  "matches": [
    {
      "id": "45392313",
      "offset": 1.23,
      "timeskew": 0.0,
      "frequencyskew": 0.0
    }
  ],
  "track": {
    "title": "Blinding Lights",
    "subtitle": "The Weeknd",
    "url": "https://www.shazam.com/track/45392313",
    "genres": {
      "primary": "Pop"
    },
    "sections": [
      {
        "type": "SONG",
        "metadata": [
          { "title": "Album", "text": "After Hours" },
          { "title": "Label", "text": "Republic Records" },
          { "title": "Released", "text": "2019" }
        ]
      }
    ]
  }
}

​
No Match

{
  "matched": false,
  "matches": [],
  "track": null
}

​
Supported File Types

FormatExtension
MPEG Audio.mp3
MPEG-4 Video.mp4
MPEG-4 Audio.m4a
Waveform Audio.wav
Ogg Vorbis.ogg
Free Lossless Audio.flac
Advanced Audio Coding.aac
WebM Audio/Video.webm
Maximum file size is 10 MB. Files exceeding this limit will return a 400 error.