API Documentation

TOPSPAWN public API v1

The TOPSPAWN API allows server owners to verify votes and automatically reward players via plugins on their game servers.

Quick start

1Generate your API key in the Dashboard → Integrations
2Test with curl: curl -H "Authorization: Bearer your_key" https://topspawn.com/api/v1/server/info
3Integrate into your Minecraft, FiveM, or any other game server plugin

Authentication

All requests must include your API key via the Authorization header:

Authorization Header

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  https://www.topspawn.com/api/v1/server/info

Rate limit: 60 requests per minute per API key. If exceeded, the API returns a 429.

Endpoints

GET/api/v1/vote/check

Check if a player has voted for your server in the last 2 hours.

Parameters

Name	Type	Required	Description
`username`	string	yes	The player's in-game username
`ip`	string	no	The player's IP address (alternative to username)

curl example

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  "https://www.topspawn.com/api/v1/vote/check?username=Steve"

Response

{
  "voted": true,
  "voted_at": "2026-03-21T14:30:00.000Z",
  "username": "Steve"
}

POST/api/v1/vote/claim

Mark a vote as claimed (reward distributed). Prevents rewarding the same vote twice.

Parameters

Name	Type	Required	Description
`username`	string	yes	The player's username (in the JSON body)

curl example

curl -X POST \
  -H "Authorization: Bearer ts_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "Steve"}' \
  "https://www.topspawn.com/api/v1/vote/claim"

Response

{
  "success": true,
  "vote_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

GET/api/v1/vote/count

Retrieve your server's vote statistics.

curl example

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  "https://www.topspawn.com/api/v1/vote/count"

Response

{
  "votes_total": 1234,
  "votes_24h": 42,
  "votes_7d": 287,
  "votes_monthly": 890,
  "server_name": "Mon Serveur",
  "server_game": "minecraft"
}

GET/api/v1/server/info

Retrieve your server's public information.

curl example

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  "https://www.topspawn.com/api/v1/server/info"

Response

{
  "name": "Mon Serveur",
  "game": "minecraft",
  "ip": "play.monserveur.fr",
  "port": 25565,
  "description": "Un super serveur survie !",
  "is_premium": false,
  "is_verified": true,
  "votes_total": 1234,
  "followers_count": 56,
  "rank": 12
}

Error codes

Code	Description
`200`	Success
`400`	Missing or invalid parameter
`401`	Missing or invalid API key
`404`	Resource not found (e.g. no unclaimed vote)
`429`	Rate limit exceeded (60 req/min)
`500`	Internal server error

FiveM Plugin

Ready-to-use Lua plugin to automatically reward your FiveM players when they vote. Compatible with ESX, QBCore, QBox and standalone.

Quick installation

1.Download the topspawn-votes folder and place it in resources/
2.Add ensure topspawn-votes to server.cfg
3.Open config.lua and paste your API key
4.Configure the reward type (money, bank, item, custom)
5.Restart your server

Download plugin

Ready to integrate?

Generate your API key and start rewarding your players in minutes.

Generate my API key