Skip to main content

​
Introduction

Lavalink provides two primary APIs for controlling audio playback in Discord bots:
  • REST API - For managing players, loading tracks, and controlling playback
  • WebSocket API - For real-time player state updates and event notifications
Both APIs work together to provide a complete audio solution. The REST API handles commands and configuration, while the WebSocket API provides live updates about player state and events.

​
API Versions

Lavalink uses versioned API endpoints:
  • /v4/* - Current API version (v4.0.0+)
  • /v3/* - Legacy API version (v3.7.0+)
  • /version - Version endpoint (no prefix)
Routes without an API prefix were removed in v4, except for the /version endpoint.

​
Architecture

┌─────────────────┐
│   Discord Bot   │
└────────┬────────┘
         │
         │ WebSocket Connection
         │ (events, updates)
         │
         ├─────────────────┐
         │                 │
         │ REST Requests   │
         │ (control)       │
         │                 │
         ▼                 ▼
┌─────────────────────────────┐
│      Lavalink Server        │
│  ┌─────────────────────┐    │
│  │   WebSocket API     │    │
│  │   - Player Updates  │    │
│  │   - Events          │    │
│  │   - Stats           │    │
│  └─────────────────────┘    │
│  ┌─────────────────────┐    │
│  │     REST API        │    │
│  │   - Load Tracks     │    │
│  │   - Update Player   │    │
│  │   - Manage Session  │    │
│  └─────────────────────┘    │
└──────────┬──────────────────┘
           │
           │ Voice Connection
           ▼
┌─────────────────────────────┐
│   Discord Voice Servers     │
└─────────────────────────────┘

​
Core Components

​
Sessions

A session represents a connection between your client and Lavalink. Each WebSocket connection creates a session with a unique session ID. Sessions can be configured for resuming to maintain playback during reconnections.

​
Players

Players are per-guild entities that manage audio playback. Each guild you want to play audio in requires its own player. Players are created automatically when you update them via the REST API.

​
Tracks

Tracks are audio resources loaded from various sources (YouTube, SoundCloud, etc.). Tracks are identified by a base64-encoded string that contains metadata and playback information.

​
API Endpoints Overview

​
REST API

Endpoint CategoryPurposeExamples
Track APILoad and decode tracks/v4/loadtracks, /v4/decodetrack
Player APIControl playback/v4/sessions/{sessionId}/players/{guildId}
Session APIManage connections/v4/sessions/{sessionId}
Info APIServer information/v4/info, /v4/stats
RoutePlanner APIIP rotation/v4/routeplanner/status

​
WebSocket API

OP TypePurposeDirection
readyConnection establishedServer → Client
playerUpdatePlayer state updatesServer → Client
statsServer statisticsServer → Client
eventPlayer/voice eventsServer → Client

​
Common Data Types

​
Track Object

Represents an audio track with metadata: 
{
  "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5...",
  "info": {
    "identifier": "dQw4w9WgXcQ",
    "isSeekable": true,
    "author": "RickAstleyVEVO",
    "length": 212000,
    "isStream": false,
    "position": 0,
    "title": "Rick Astley - Never Gonna Give You Up",
    "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "sourceName": "youtube"
  }
}

​
Player Object

Represents the current state of a player: 
{
  "guildId": "817327181659111454",
  "track": { /* Track object */ },
  "volume": 100,
  "paused": false,
  "state": {
    "time": 1500467109,
    "position": 60000,
    "connected": true,
    "ping": 50
  },
  "voice": {
    "token": "...",
    "endpoint": "...",
    "sessionId": "..."
  }
}

​
Error Handling

All REST endpoints return structured error responses: 
{
  "timestamp": 1667857581613,
  "status": 404,
  "error": "Not Found",
  "message": "Session not found",
  "path": "/v4/sessions/xtaug914v9k5032f/players/817327181659111454"
}
Include trace=true as a query parameter to receive stack traces for debugging.

​
Next Steps

Implementation Guide

Learn how to integrate Lavalink with your Discord bot

Authentication

Set up authentication and secure connections

REST API Reference

Explore REST API endpoints

WebSocket API

Real-time events and updates

Build docs developers (and LLMs) love

Get started for freeTalk to us