Skip to main content

​
Update Session

Configure session resuming behavior and timeout settings. 
PATCH /v4/sessions/{sessionId}

​
Path Parameters

​
sessionId
string
required
The session ID obtained from the WebSocket ready event

​
Request Body

​
resuming
boolean
Whether resuming is enabled for this session. When enabled, the session can be resumed after a disconnect using the Session-Id header when reconnecting via WebSocket.
​
timeout
integer
The timeout in seconds before the session is destroyed after a disconnect. Default is 60 seconds. Set to 0 to destroy immediately.
Session ResumingWhen resuming is enabled:
  1. Your WebSocket connection is assigned a session ID (received in the ready OP)
  2. If you disconnect, the session remains active for the configured timeout period
  3. Reconnect with the Session-Id header to resume the session
  4. All players and their state will be preserved
This is useful for maintaining playback during brief network interruptions or bot restarts.

​
Response

​
resuming
boolean
required
Whether resuming is currently enabled for this session
​
timeout
integer
required
The current timeout in seconds
curl -X PATCH 'http://localhost:2333/v4/sessions/xtaug914v9k5032f' \
  -H 'Authorization: youshallnotpass' \
  -H 'Content-Type: application/json' \
  -d '{
    "resuming": true,
    "timeout": 60
  }'

​
RoutePlanner API

The RoutePlanner API manages IP rotation for bypassing rate limits. This is useful when running Lavalink with multiple IP addresses.

​
Get RoutePlanner Status

Retrieve the current RoutePlanner configuration and status. 
GET /v4/routeplanner/status

​
Response

When RoutePlanner is disabled: Returns 204 No Content When RoutePlanner is enabled: Returns 200 OK with:
​
class
string
The RoutePlanner implementation type:
  • RotatingIpRoutePlanner - Switches IP on ban (recommended for IPv4 blocks or IPv6 blocks smaller than /64)
  • NanoIpRoutePlanner - Switches IP on clock update (use with at least 1 /64 IPv6 block)
  • RotatingNanoIpRoutePlanner - Switches IP on clock update, rotates to different /64 block on ban (use with at least 2x /64 IPv6 blocks)
  • BalancingIpRoutePlanner - Selects random IP per request (recommended for larger IP blocks)
​
details
object
RoutePlanner status details
curl -X GET 'http://localhost:2333/v4/routeplanner/status' \
  -H 'Authorization: youshallnotpass'

​
Unmark Failed Address

Remove a specific address from the failed addresses list. 
POST /v4/routeplanner/free/address

​
Request Body

​
address
string
required
The IP address to unmark as failed. This address must be within the same IP block configured for the RoutePlanner.

​
Response

Returns 204 No Content on success. 
curl -X POST 'http://localhost:2333/v4/routeplanner/free/address' \
  -H 'Authorization: youshallnotpass' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "1.0.0.1"
  }'

​
Unmark All Failed Addresses

Clear all addresses from the failed addresses list. 
POST /v4/routeplanner/free/all

​
Response

Returns 204 No Content on success. 
curl -X POST 'http://localhost:2333/v4/routeplanner/free/all' \
  -H 'Authorization: youshallnotpass'

​
Session Best Practices

Enable resuming if:
  • Your bot experiences occasional brief disconnections
  • You need to restart your bot without interrupting music playback
  • You want to maintain player state across reconnections
Disable resuming if:
  • You’re running in a serverless environment
  • You want fresh sessions on each connection
  • You don’t need state persistence
  • 60 seconds (default): Good for most applications
  • 300+ seconds: For slow restart processes or expected longer downtimes
  • 0 seconds: Destroy session immediately on disconnect (effectively disables resuming)
Consider your bot’s typical restart time and network stability when configuring the timeout.
Choose based on your IP configuration:
  • RotatingIpRoutePlanner: Best for IPv4 blocks or small IPv6 blocks (< /64)
  • NanoIpRoutePlanner: Best for single /64 IPv6 blocks
  • RotatingNanoIpRoutePlanner: Best when you have multiple /64 IPv6 blocks
  • BalancingIpRoutePlanner: Best for very large IP blocks (distributes load randomly)

Build docs developers (and LLMs) love

Get started for freeTalk to us