API Reference
REST API
HTTP endpoints for managing audio and sessions.
REST API
The REST API allows you to manage sessions, players, and resolve audio tracks. All endpoints are prefixed with /v4.
Common Types
Represents an audio track with encoded data and metadata.
Track Fields
encodedstringRequired
The base64 encoded track data
infoobjectRequired
Info about the track (see Track Info below)
pluginInfoobject
Additional track info provided by plugins
userDataobject
Additional track data provided via the Update Player endpoint
Track Info Fields
identifierstringRequired
The track identifier
isSeekableboolRequired
Whether the track is seekable
authorstringRequired
The track author
lengthintRequired
The track length in milliseconds
isStreamboolRequired
Whether the track is a stream
positionintRequired
The track position in milliseconds
titlestringRequired
The track title
uristring | null
The track uri
artworkUrlstring | null
The track artwork url
isrcstring | null
The track ISRC (International Standard Recording Code)
sourceNamestringRequired
The track source name
Example
{
"encoded": "QAAAAAMARFJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAgKE9mZmljaWFsIFZpZGVvKSAoNEsgUmVtYXN0ZXIpAAtSaWNrIEFzdGxleQAAAAAAA0PwAAtkUXc0dzlXZ1hjUQABACtodHRwczovL3d3dy55b3V0dWJlLmNvbS93YXRjaD92PWRRdzR3OVdnWGNRAQA2aHR0cHM6Ly9pLnl0aW1nLmNvbS92aV93ZWJwL2RRdzR3OVdnWGNRL3NkZGVmYXVsdC53ZWJwAAAHeW91dHViZQAAAAAAAAAA",
"info": {
"identifier": "dQw4w9WgXcQ",
"isSeekable": true,
"author": "Rick Astley",
"length": 214000,
"isStream": false,
"position": 0,
"title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
"uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"artworkUrl": "https://i.ytimg.com/vi_webp/dQw4w9WgXcQ/sddefault.webp",
"isrc": null,
"sourceName": "youtube"
},
"pluginInfo": {}
}Tracks & Items
Resolves audio tracks for use in playback. Supports direct URLs, search queries, and playlists.
Example Request
curl -X GET "http://your-server.com/v4/loadtracks?identifier=ytsearch:never%20gonna%20give%20you%20up" \
-H "Authorization: yourPassword"Query Parameters
identifierstringRequired
URL, search query (prefix: ytsearch:, spsearch:, scsearch:), or playlist URL
Response
Decodes a base64 encoded track string into track information.
Example Request
curl -X GET "http://your-server.com/v4/decodetrack?encodedTrack=QAAAjQIAJVJpY2sgQXN0bGV5..." \
-H "Authorization: yourPassword"Query Parameters
encodedTrackstringRequired
The base64 encoded track string
Response
Decodes multiple base64 encoded track strings at once.
Example Request
curl -X POST "http://your-server.com/v4/decodetracks" \
-H "Authorization: yourPassword" \
-H "Content-Type: application/json" \
-d '["QAAAjQIAJVJpY2sgQXN0bGV5...","QAAAkAIAJU90aGVyIFRyYWNr..."]'Body
tracksstring[]Required
Array of base64 encoded track strings
Response
Encodes a track object into a base64 string.
Query Parameters
trackobjectRequired
The track object to encode.
Response
Example Request
curl -X GET "http://your-server.com/v4/encodetrack?track=%7B%22identifier%22%3A%22dQw4w9WgXcQ%22%2C%22title%22%3A%22Rick%20Astley%20-%20Never%20Gonna%20Give%20You%20Up%22%2C%22author%22%3A%22Rick%20Astley%22%2C%22length%22%3A214000%2C%22uri%22%3A%22https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ%22%2C%22sourceName%22%3A%22youtube%22%7D" \
-H "Authorization: yourPassword"Encodes multiple track objects into base64 strings at once.
Body
Array of track objects to encode, where each track has:
encodedstring
Existing encoded track (if re-encoding)
infoobject
Track info object with identifier, title, author, uri, sourceName, etc.
Example Request
curl -X POST "http://your-server.com/v4/encodedtracks" \
-H "Authorization: yourPassword" \
-H "Content-Type: application/json" \
-d '[
{
"info": {
"identifier": "dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up",
"author": "Rick Astley",
"length": 214000,
"uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"sourceName": "youtube"
}
},
{
"info": {
"identifier": "invalid_track",
"title": "Invalid Track",
"author": "Unknown",
"length": 0,
"uri": "https://example.com/invalid",
"sourceName": "http"
}
}
]'Response
Players & Sessions
Returns all players in the specified session.
Example Request
curl -X GET "http://your-server.com/v4/sessions/yourSessionId/players" \
-H "Authorization: yourPassword"Response
Returns the player for a specific guild.
Example Request
curl -X GET "http://your-server.com/v4/sessions/yourSessionId/players/yourGuildId" \
-H "Authorization: yourPassword"Response
PATCH
/v4/sessions/{sessionId}/players/{guildId}
Updates or creates a player for a guild.
Query Parameters
noReplaceboolean
If true, won't replace the currently playing track with the new one
Body Parameters
track.encodedstring
Base64 encoded track to play (null to stop)
track.identifierstring
Track identifier to resolve and play
track.userDataobject
Custom data to attach to the track
positionnumber
Track position in milliseconds (min: 0)
endTimenumber
When to stop the track in milliseconds (null to reset)
volumenumber
Player volume from 0 to 1000 (100 = 100%)
pausedboolean
Whether the player should be paused
filtersobject
Audio filters to apply (see Filters section)
voice.tokenstring
Discord voice token
voice.endpointstring
Discord voice endpoint
voice.sessionIdstring
Discord voice session ID
Example Request
curl -X PATCH "http://your-server.com/v4/sessions/yourSessionId/players/yourGuildId?noReplace=false" \
-H "Authorization: yourPassword" \
-H "Content-Type: application/json" \
-d '{
"track": {
"encoded": "QAAAjQIAJVJpY2sgQXN0bGV5..."
},
"volume": 100,
"filters": {
"equalizer": [
{"band": 0, "gain": 0.2}
]
}
}'Response
DELETE
/v4/sessions/{sessionId}/players/{guildId}
Destroys the player for a guild.
Example Request
curl -X DELETE "http://your-server.com/v4/sessions/yourSessionId/players/yourGuildId" \
-H "Authorization: yourPassword"Response
Updates session configuration.
Body
resumingboolean
Whether resuming is enabled for this session.
timeoutnumber
The timeout in seconds for resuming.
Example Request
curl -X PATCH "http://your-server.com/v4/sessions/yourSessionId" \
-H "Authorization: yourPassword" \
-H "Content-Type: application/json" \
-d '{"resuming": true, "timeout": 60}'Response
Node Information
Returns the connection manager status and metrics.
Example Request
curl -X GET "http://your-server.com/v4/connection" \
-H "Authorization: yourPassword"Response
Returns detailed information about the NodeLink server, including version, supported sources, filters, and build information.
Example Request
curl -X GET "http://your-server.com/v4/info" \
-H "Authorization: yourPassword"Response
Returns real-time statistics about server resource usage, active players, and detailed metrics.
Example Request
curl -X GET "http://your-server.com/v4/stats" \
-H "Authorization: yourPassword"Response
Returns the plain text version of NodeLink. Note: This endpoint is at /version (not /v4/version) for Lavalink client compatibility.
Example Request
curl -X GET "http://your-server.com/version"Response
NodeLink Specific
Loads synchronized or plain text lyrics for a track from various sources.
Example Request
curl -X GET "http://your-server.com/v4/loadlyrics?encodedTrack=QAAAjQIAJVJpY2sgQXN0bGV5..." \
-H "Authorization: yourPassword"Query Parameters
encodedTrackstringRequired
Base64 encoded track string
langstring
Language code for lyrics (e.g., 'en', 'es', 'pt')
Response
Loads chapter markers for YouTube videos that have them.
Example Request
curl -X GET "http://your-server.com/v4/loadchapters?encodedTrack=QAAAAAMAM0hvdyB0byBBZGQgQ2hhcHRlcnMgdG8gWW91ciBWaWRlb3MgVXNpbmcgVGltZXN0YW1wcwAQWW91VHViZSBDcmVhdG9ycwAAAAAAATSYAAtiMUZvX01fdGo2dwABACtodHRwczovL3d3dy55b3V0dWJlLmNvbS93YXRjaD92PWIxRm9fTV90ajZ3AQA2aHR0cHM6Ly9pLnl0aW1nLmNvbS92aV93ZWJwL2IxRm9fTV90ajZ3L3NkZGVmYXVsdC53ZWJwAAAHeW91dHViZQAAAAAAAAAA" \
-H "Authorization: yourPassword"Query Parameters
encodedTrackstringRequired
Base64 encoded track string (YouTube only)
Response
Directly streams the track audio (if enabled).
Query Parameters
encodedTrackstringRequired
The base64 encoded track.
itagnumber
Target specific YouTube itag.
Example Request
curl -X GET "http://your-server.com/v4/trackstream?encodedTrack=QAAAAAMAM0hvdyB0byBBZGQgQ2hhcHRlcnMgdG8gWW91ciBWaWRlb3MgVXNpbmcgVGltZXN0YW1wcwAQWW91VHViZSBDcmVhdG9ycwAAAAAAATSYAAtiMUZvX01fdGo2dwABACtodHRwczovL3d3dy55b3V0dWJlLmNvbS93YXRjaD92PWIxRm9fTV90ajZ3AQA2aHR0cHM6Ly9pLnl0aW1nLmNvbS92aV93ZWJwL2IxRm9fTV90ajZ3L3NkZGVmYXVsdC53ZWJwAAAHeW91dHViZQAAAAAAAAAA&itag=251" \
-H "Authorization: yourPassword"Response
Route Planner
Returns the current status of the route planner.
Example Request
curl -X GET "http://your-server.com/v4/routeplanner/status" \
-H "Authorization: yourPassword"Unmarks a failed address.
Body
addressstringRequired
The IP address to free.
Example Request
curl -X POST "http://your-server.com/v4/routeplanner/free/address" \
-H "Authorization: yourPassword" \
-H "Content-Type: application/json" \
-d '{"address": "192.168.1.1"}'Unmarks all failed addresses.
Example Request
curl -X POST "http://your-server.com/v4/routeplanner/free/all" \
-H "Authorization: yourPassword"Audio Filters
NodeLink supports a variety of audio filters that can be applied in real-time to modify playback. Filters are applied through the filters object in the Update Player request.
How to Apply Filters
Send filters in the Update Player request:
curl -X PATCH "http://your-server.com/v4/sessions/{sessionId}/players/{guildId}" \
-H "Authorization: yourPassword" \
-H "Content-Type: application/json" \
-d '{
"filters": {
"equalizer": [
{"band": 0, "gain": 0.2}
],
"echo": {
"delay": 500,
"feedback": 0.3,
"mix": 0.5
}
}
}'You can combine multiple filters simultaneously. NodeLink processes them efficiently in the audio pipeline.
Standard Filters
15-band equalizer for precise frequency control
Parameters
bandnumber
Band index from 0 to 14
gainnumber
Gain multiplier from -0.25 to 1.0 (0 = no change, -0.25 = muted, 1.0 = doubled)
Frequency Bands
| Band | Frequency | Description |
|---|---|---|
| 0 | 25 Hz | Sub-bass |
| 1 | 40 Hz | Bass |
| 2 | 63 Hz | Bass |
| 3 | 100 Hz | Bass |
| 4 | 160 Hz | Low-mid |
| 5 | 250 Hz | Low-mid |
| 6 | 400 Hz | Mid |
| 7 | 630 Hz | Mid |
| 8 | 1 kHz | Mid |
| 9 | 1.6 kHz | Upper-mid |
| 10 | 2.5 kHz | Upper-mid |
| 11 | 4 kHz | Presence |
| 12 | 6.3 kHz | Presence |
| 13 | 10 kHz | Brilliance |
| 14 | 16 kHz | Air |
Example Usage
{
"filters": {
"equalizer": [
{"band": 0, "gain": 0.2},
{"band": 1, "gain": 0.15},
{"band": 2, "gain": 0.1}
]
}
}Reduces vocals by eliminating frequencies in a specific band
Parameters
levelnumber
Effect intensity from 0.0 to 1.0
monoLevelnumber
Mono channel intensity from 0.0 to 1.0
filterBandnumber
Target frequency band in Hz
filterWidthnumber
Width of the frequency filter
Changes playback speed, pitch, and rate independently
Parameters
speednumber
Playback speed multiplier (1.0 = normal, must be > 0)
pitchnumber
Pitch shift multiplier (1.0 = normal, must be > 0)
ratenumber
Rate change multiplier (1.0 = normal, must be > 0)
Creates volume oscillation effect
Parameters
frequencynumber
Oscillation frequency in Hz (must be > 0)
depthnumber
Effect depth from 0.0 to 1.0
Creates pitch oscillation effect
Parameters
frequencynumber
Oscillation frequency from 0.0 to 14.0 Hz
depthnumber
Effect depth from 0.0 to 1.0
Rotates audio around the stereo field (8D audio effect)
Parameters
rotationHznumber
Rotation speed in Hz (0.2 is recommended for smooth rotation)
Applies distortion using sine, cosine, and tangent waves
Parameters
sinOffsetnumber
Sine wave offset
sinScalenumber
Sine wave scale multiplier
cosOffsetnumber
Cosine wave offset
cosScalenumber
Cosine wave scale multiplier
tanOffsetnumber
Tangent wave offset
tanScalenumber
Tangent wave scale multiplier
offsetnumber
General offset
scalenumber
General scale multiplier
Mixes left and right audio channels with custom ratios
Parameters
leftToLeftnumber
Left to left channel factor (0.0 to 1.0, default: 1.0)
leftToRightnumber
Left to right channel factor (0.0 to 1.0, default: 0.0)
rightToLeftnumber
Right to left channel factor (0.0 to 1.0, default: 0.0)
rightToRightnumber
Right to right channel factor (0.0 to 1.0, default: 1.0)
Filters out high frequencies, letting low frequencies pass through
Parameters
smoothingnumber
Smoothing factor (must be > 1.0 to enable, higher values = more aggressive filtering)
NodeLink Exclusive Filters
These filters are unique to NodeLink, built from scratch with custom DSP implementations.
Creates delay-based echo with feedback control
Parameters
delaynumber
Delay time in milliseconds (0 to 5000ms)
feedbacknumber
Amount of signal fed back into the delay (0.0 to 1.0)
mixnumber
Dry/wet mix ratio (0.0 = dry only, 1.0 = wet only)
Example Usage
{
"filters": {
"echo": {
"delay": 500,
"feedback": 0.3,
"mix": 0.5
}
}
}Simulates multiple voices playing together with modulated delays
Parameters
ratenumber
LFO modulation rate in Hz
depthnumber
Modulation depth (0.0 to 1.0)
delaynumber
Base delay time in milliseconds (1 to 45ms)
mixnumber
Dry/wet mix ratio (0.0 to 1.0)
feedbacknumber
Feedback amount (0.0 to 0.95)
Dynamic range compression for balanced audio levels
Parameters
thresholdnumber
Threshold level in dB (when compression starts)
rationumber
Compression ratio (1.0 = no compression, higher = more compression)
attacknumber
Attack time in milliseconds (how fast compression engages)
releasenumber
Release time in milliseconds (how fast compression disengages)
gainnumber
Makeup gain in dB (compensates for volume reduction)
Filters out low frequencies, letting high frequencies pass through
Parameters
smoothingnumber
Smoothing factor (must be > 1.0 to enable)
Sweeps all-pass filters across the frequency spectrum for a swooshing effect
Parameters
stagesnumber
Number of filter stages (2 to 12, more = stronger effect)
ratenumber
LFO sweep rate in Hz
depthnumber
Modulation depth (0.0 to 1.0)
feedbacknumber
Feedback amount (0.0 to 0.9)
mixnumber
Dry/wet mix ratio (0.0 to 1.0)
minFrequencynumber
Minimum sweep frequency in Hz
maxFrequencynumber
Maximum sweep frequency in Hz
Creates spatial audio using cross-channel delays and modulation
Parameters
depthnumber
Effect depth (0.0 to 1.0)
ratenumber
Modulation rate in Hz