Documentation navigation

Server API v1

The Server API allows game server plugins and mods to report status updates and query server information programmatically.

Overview

The Server API enables your game server to communicate with PalworldServers.io. Use it to keep your server's status up-to-date, report player counts, and retrieve public server information.

Key Details

Authentication via server key (64-character hex string from your dashboard)
Base URL: https://palworldservers.io/api/v1
All responses are JSON
Rate limited to prevent abuse

Endpoints

GET/api/v1/server/{serverId}

Retrieve public information about a server. No authentication required.

Parameters

Name	Location	Description
serverId	Path	UUID of the server

Authentication

None required. This is a public endpoint.

Response

200 OK - Response Example

{
  "server": {
    "id": "uuid",
    "name": "My Server",
    "ip": "192.168.1.1",
    "port": 8211,
    "description": "...",
    "isOnline": true,
    "currentPlayers": 12,
    "maxPlayers": 32,
    "version": "0.3.4",
    "country": "US",
    "votesCount": 150,
    "viewCount": 2000,
    "isFeatured": false,
    "createdAt": "2026-01-01T00:00:00Z",
    "lastWipedAt": "2026-07-01T00:00:00Z",
    "config": { "xp": 2, "taming": 1.5, "drop": 3 }
  }
}

POST/api/v1/server/update/{serverKey}

Update your server's status including player count, version, and online status. Calling this endpoint automatically marks the server as online.

If this endpoint is not called for 5 minutes, the background worker may mark your server as offline. Set up a periodic heartbeat (every 60 seconds recommended) to maintain online status.

Parameters

Name	Location	Description
serverKey	Path	64-character hex server key from dashboard

Request Body

All fields are optional. Send only what you want to update.

Field	Type	Description
players	number	Current number of players online
maxPlayers	number	Maximum player capacity
version	string	Game version running on the server
map	string	Current map name
worldGuid	string	World GUID identifier

Request Example

POST Body

{
  "players": 12,
  "maxPlayers": 32,
  "version": "0.3.4",
  "map": "MainWorld",
  "worldGuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

200 OK - Response Example

{
  "success": true,
  "message": "Server status updated successfully",
  "server": {
    "id": "uuid",
    "name": "My Server",
    "isOnline": true,
    "currentPlayers": 12,
    "maxPlayers": 32
  }
}

Server Key

Your server key is a unique 64-character hexadecimal string that authenticates API requests from your game server.

How to Get Your Server Key

Log in to your PalworldServers.io dashboard
Navigate to My Servers
Click on the server you want to configure
Go to the Edit tab
Your server key is displayed in the API section

Regenerating Your Key

If your key is compromised, you can regenerate it from the same dashboard page. Note that regenerating invalidates the old key immediately.

Security Warning

Treat your server key as a secret. Never commit it to version control, share it publicly, or expose it in client-side code. Use environment variables to store it securely.

Code Examples

Lua - Periodic Heartbeat

Send a heartbeat every 60 seconds to keep your server marked as online and update player count.

Lua - Server Heartbeat Plugin

-- Configuration
local SERVER_KEY = "your_64_char_hex_server_key_here"
local API_URL = "https://palworldservers.io/api/v1/server/update/" .. SERVER_KEY
local HEARTBEAT_INTERVAL = 60 -- seconds

-- Send heartbeat to PalworldServers.io
function SendHeartbeat()
  local playerCount = GetCurrentPlayerCount()
  local maxPlayers = GetMaxPlayers()
  local version = GetServerVersion()

  local payload = json.encode({
    players = playerCount,
    maxPlayers = maxPlayers,
    version = version,
    map = GetCurrentMap()
  })

  HttpPost(API_URL, payload, {
    ["Content-Type"] = "application/json"
  }, function(response, status)
    if status == 200 then
      Log("[PalworldServers] Heartbeat sent successfully")
    else
      Log("[PalworldServers] Heartbeat failed: " .. tostring(status))
    end
  end)
end

-- Register the heartbeat timer
RegisterTimer(HEARTBEAT_INTERVAL * 1000, SendHeartbeat)
Log("[PalworldServers] Heartbeat plugin loaded - reporting every " .. HEARTBEAT_INTERVAL .. "s")

Python - Status Reporter

A standalone Python script that periodically reports server status via the API.

Python - Server Status Reporter

import requests
import time
import os

SERVER_KEY = os.environ.get("PALWORLD_SERVER_KEY", "your_64_char_hex_key")
API_URL = f"https://palworldservers.io/api/v1/server/update/{SERVER_KEY}"
INTERVAL = 60  # seconds

def get_server_status():
    """Replace with your actual server status retrieval logic."""
    # Example: query RCON or read from a status file
    return {
        "players": 12,
        "maxPlayers": 32,
        "version": "0.3.4",
        "map": "MainWorld"
    }

def send_heartbeat():
    status = get_server_status()
    try:
        response = requests.post(API_URL, json=status, timeout=10)
        if response.status_code == 200:
            data = response.json()
            print(f"[OK] Heartbeat sent - {data['server']['currentPlayers']} players")
        else:
            print(f"[ERR] Status {response.status_code}: {response.text}")
    except requests.RequestException as e:
        print(f"[ERR] Request failed: {e}")

if __name__ == "__main__":
    print(f"Starting PalworldServers.io heartbeat (every {INTERVAL}s)")
    while True:
        send_heartbeat()
        time.sleep(INTERVAL)

Error Codes

Status	Meaning	Common Causes
400	Bad Request	Missing or invalid fields in request body, malformed JSON
403	Forbidden	Server not approved yet, or has been suspended
404	Not Found	Invalid server ID or server key, server does not exist
429	Rate Limited	Too many requests. Wait and retry with exponential backoff
500	Server Error	Internal error on our end. Try again later or contact support

Error Response Format

Error Response Example

{
  "error": "Invalid server key",
  "status": 404
}