API Documentation

All public JSON endpoints for server listings, voting, and vote history.

Public Read Endpoints

No authentication required. Available to everyone.

GET
/api/vote/<server_id>

Returns the current month vote count for a server.

{
  "server_id": 1,
  "votes": 42,
  "year": 2026,
  "month": 6
}
GET
/vote/<server_id>

Same as above. Returns current month vote count.

GET
/vote/<server_id>/history

Returns vote history for the last 6 months.

[
  {"year": 2026, "month": 1, "votes": 35},
  {"year": 2026, "month": 2, "votes": 42},
  ...
]
GET
/sitemap.xml

Returns XML sitemap with all public pages and active servers.

Voting Endpoints

Web voting and API voting with cooldown. Each user/IP can vote once per 24 hours per server.

POST
/vote/<server_id>

Browser vote. Requires login or uses IP address. Returns vote count or cooldown error.

POST
/api/vote/<server_id>

API vote with key authentication. For Discord bots and external integrations.

Headers:

X-API-Key: your-server-api-key
Content-Type: application/json

Body (optional):

{"discord_id": "123456789"}

Discord Bot Integration

Allow users to vote directly from your Discord server. Each server owner sets their own API Vote Key in the server edit form.

Setup Steps:
  1. Go to your server edit page and generate an API Vote Key.
  2. Add the key to your Discord bot code.
  3. Users can now vote with a /vote command.
# Discord Bot Vote Command (discord.py)
import aiohttp

API_KEY = "your-server-api-vote-key"
BASE_URL = "https://palserves.online"

async def vote_server(server_id, discord_user_id):
    async with aiohttp.ClientSession() as session:
        headers = {"X-API-Key": API_KEY}
        payload = {"discord_id": str(discord_user_id)}
        async with session.post(
            f"{BASE_URL}/api/vote/{server_id}",
            headers=headers, json=payload
        ) as resp:
            return await resp.json()

@bot.tree.command(name="vote", description="Vote for this server")
async def vote_cmd(interaction: discord.Interaction):
    result = await vote_server(1, interaction.user.id)
    if result.get("success"):
        await interaction.response.send_message(f"Vote counted! Total: {result['votes']}")
    else:
        await interaction.response.send_message(f"Already voted. Wait {result.get('hours_remaining', 24)}h")

cURL Examples

Get vote count:

curl "https://palserves.online/api/vote/1"

Vote via API:

curl -X POST "https://palserves.online/api/vote/1" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discord_id":"123456789"}'

Get vote history:

curl "https://palserves.online/vote/1/history"

Response Codes

200 OK — Request successful
401 Unauthorized — Missing API key
403 Forbidden — Invalid API key
429 Too Many Requests — Vote cooldown active
404 Not Found — Server does not exist

Ratenlimits

60 requests per minute per IP. Each user or Discord ID can vote once per 24 hours per server. Votes reset monthly for the leaderboard.