API Reference

Rustalink implements the Lavalink v4 API. Authenticate using the Authorization header.

Authorization: youshallnotpass

Common Types

These types are used across various REST and WebSocket payloads.

Type	Description	Details
Track	Audio track metadata	View
Stats	Server usage statistics	View
Player State	Current player runtime data	View

Track Object Fields

Field	Type	Description
`encoded`	string	The base64 encoded track data
`info`	object	Track Info details
`pluginInfo`	object	Additional info provided by plugins
`userData`	object	Custom data attached via Update Player

Track Info Fields

Field	Type	Description
`identifier`	string	The track identifier
`isSeekable`	boolean	Whether the track is seekable
`author`	string	The track author
`length`	number	The track length in milliseconds
`isStream`	boolean	Whether the track is a stream
`position`	number	The track position in milliseconds
`title`	string	The track title
`uri`	string	The track URI
`artworkUrl`	string	The track artwork URL
`isrc`	string	The track ISRC
`sourceName`	string	The track source name

Stats Object Fields

Field	Type	Description
`players`	number	Connected players
`playingPlayers`	number	Active players
`uptime`	number	Uptime in ms
`memory`	object	`free`, `used`, `allocated`, `reservable`
`cpu`	object	`cores`, `systemLoad`, `lavalinkLoad`
`frameStats`	object	`sent`, `nulled`, `deficit`

Player State Object Fields

Field	Type	Description
`guildId`	string	The guild ID of the player
`track`	object	The currently playing Track
`volume`	number	The current player volume (0-1000)
`paused`	boolean	Whether the player is paused
`state`	object	Inner state details
`voice`	object	The current Voice State
`filters`	object	Applied Filters

Player Inner State Fields

Field	Type	Description
`time`	number	The current server time in ms
`position`	number	The track position in ms
`connected`	boolean	Whether the player is connected to voice
`ping`	number	The player’s voice ping in ms

Voice State Fields

Field	Type	Description
`token`	string	The Discord voice token
`endpoint`	string	The Discord voice endpoint
`sessionId`	string	The Discord voice session ID
`channelId`	string	The Discord voice channel ID

Server Operations

Endpoint	Description	Details
GET `/v4/info`	Basic server metadata	View
GET `/v4/stats`	Performance metrics	View
GET `/version`	Plaintext version	View

GET /v4/info Details

Returns version, build time, and supported sources/filters.

Response Schema
Example

Field	Type	Description
`version`	object	`semver`, `major`, `minor`, `patch`, `preRelease`
`buildTime`	number	Build timestamp in ms
`git`	object	`branch`, `commit`, `commitTime`
`jvm`	string	JVM version (or Rust version in our case)
`lavaplayer`	string	Lavaplayer version
`sourceManagers`	string[]	Enabled source managers
`filters`	string[]	Supported filter names
`plugins`	object[]	List of loaded plugins

{
    "version": { "semver": "1.0.5", "major": 1, "minor": 0, "patch": 5 },
    "jvm": "Rust",
    "lavaplayer": "symphonia",
    "sourceManagers": ["youtube", "spotify", "jiosaavn"],
    "filters": ["volume", "equalizer", "karaoke"],
    "plugins": []
  }

GET /v4/stats Details

Uptime, memory, and CPU usage stats.

Example Response

{
    "players": 1,
    "playingPlayers": 1,
    "uptime": 298962,
    "memory": { "free": 19219042304, "used": 49045504, "allocated": 0, "reservable": 0 },
    "cpu": { "cores": 8, "systemLoad": 0.31, "lavalinkLoad": 0.00006 }
  }

Track Operations

Endpoint	Description	Details
GET `/v4/loadtracks`	Resolve a track/URL	View
GET `/v4/loadsearch`	Search for tracks	View
GET `/v4/decodetrack`	Decode single track	View
POST `/v4/decodetracks`	Decode multiple	View

GET /v4/loadtracks Details

Query Parameters:

Name	Type	Required	Description
`identifier`	string	Yes	The URL or search query to resolve

Response Body:

Field	Type	Description
`loadType`	string	`track`, `playlist`, `search`, `empty`, `error`
`data`	object / array	Depends on `loadType`. Track details or Playlist info.

Example Response:

{
"loadType": "track",
"data": {
  "encoded": "QAAAd2sAC0hlbGxvIFdvcmxk...",
  "info": { "title": "Hello World", "author": "Rust", "length": 240000, ... }
}
}

GET /v4/loadsearch Details

Parameters:

query (Query, Required): Search query string.
types (Query, Optional): Comma-separated list of types: track, album, artist, playlist, text.

Player Management

Endpoint	Description	Details
GET `/v4/sessions/{id}/players`	List all players	View
PATCH `/v4/sessions/{id}/players/{gid}`	Update player state	View
DELETE `/v4/sessions/{id}/players/{gid}`	Destroy player	View

PATCH Update Player Details

Query Params:

noReplace (Optional): If true, the track will not be replaced if one is already playing.

Body Fields:

Field	Type	Description
`track`	object	Track data containing `encoded` or `identifier`.
`position`	number	Seek position in milliseconds.
`endTime`	number	Track end time in milliseconds.
`volume`	number	The player volume (0-1000).
`paused`	boolean	Whether the player is paused.
`filters`	object	Audio filters (equalizer, karaoke, etc).
`voice`	object	`token`, `endpoint`, `sessionId`.

Example Payload

{
    "track": { "encoded": "QAAAd2sAC0hlbGxvIFdvcmxk..." },
    "volume": 80,
    "paused": false,
    "voice": {
      "token": "...",
      "endpoint": "...",
      "sessionId": "..."
    }
  }

WebSocket Events

Events are sent from server to client with an op: "event".

Type	Trigger	Details
`TrackStartEvent`	Track starts playing	View
`TrackEndEvent`	Track ends	View
`TrackExceptionEvent`	Playback error	View
`TrackStuckEvent`	Playback stuck	View
`WebSocketClosedEvent`	Voice socket error	View
`LyricsFoundEvent`	Lyrics were found	View
`LyricsNotFoundEvent`	No lyrics found	View
`LyricsLineEvent`	Synced lyrics line	View

Rustalink Extras

Services	Description	Details
Lyrics	Real-time and static lyrics	View
YouTube	Tools for YouTube streams	View

Lyrics API Details

Endpoint	Method	Description
`/v4/lyrics`	GET	Search lyrics by query or track.
`/v4/sessions/{id}/players/{gid}/lyrics/subscribe`	POST	Enable synchronized lyrics.
`/v4/sessions/{id}/players/{gid}/track/lyrics`	GET	Get lyrics for current track.

YouTube Utilities Details

Endpoint	Method	Description
`/youtube`	GET	Check YouTube source health.
`/youtube/stream/{vid}`	GET	Get direct stream URL for a video.
`/youtube/oauth/{token}`	GET	Refresh OAuth credentials.

Example: GET /youtube/stream/dQw4w9WgXcQ returns the direct audio stream URL.