API Documentation

Overview

The DPServers API allows server owners to integrate a vote-for-reward system into their game server. Players vote on our platform and you can verify that vote programmatically to deliver in-game rewards.

Authentication

All API requests require an API Key, which is tied to your server. To get your API Key:

1. Register an account and add your server.
2. Go to Dashboard > Your Server > API Key.
3. Copy the API Key and use it in your requests.

How the Vote Flow Works

POST /api/vote/init

Initiates a vote session. Returns a temporary token and a URL where the player should be redirected to vote.

Parameters

Success Response (200)

{
  "success": true,
  "token": "abc123def456...",
  "vote_url": "https://www.topdofus.com/api/vote/callback/abc123def456..."
}

Error Responses

// 400 - Missing parameters{
  "success": false,
  "error": "Missing required parameters: api_key, server_id."
}

// 401 - Invalid API key{
  "success": false,
  "error": "Invalid or revoked API key."
}

// 403 - Key/server mismatch{
  "success": false,
  "error": "API key does not match the provided server_id."
}

GET /api/vote/callback/{token}

This is the URL you redirect the player to. It's returned in the vote_url field from /api/vote/init. You do NOT call this endpoint directly.

POST /api/vote/verify

Check whether a vote has been completed for a given token.

Parameters

Success Response (200)

// Player has voted{
  "success": true,
  "voted": true,
  "voted_at": "2026-04-11 14:30:00"
}

// Player has not voted yet{
  "success": true,
  "voted": false,
  "voted_at": null
}

Code Examples

PHP

<?php
$apiKey   = 'YOUR_API_KEY';
$serverId = 1;

// Step 1: Init vote
$ch = curl_init('https://www.topdofus.com/api/vote/init');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => [
        'api_key'   => $apiKey,
        'server_id' => $serverId,
        'username'  => 'player123',
    ],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['success']) {
    // Redirect user to vote
    header('Location: ' . $response['vote_url']);
    exit;
}

// Step 2: Verify vote (after user returns)
$ch = curl_init('https://www.topdofus.com/api/vote/verify');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => [
        'api_key' => $apiKey,
        'token'   => $response['token'],
    ],
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['success'] && $result['voted']) {
    echo 'Vote confirmed! Reward the player.';
}

JavaScript (fetch)

const API_KEY   = 'YOUR_API_KEY';
const SERVER_ID = 1;

// Step 1: Init vote
const formData = new FormData();
formData.append('api_key', API_KEY);
formData.append('server_id', SERVER_ID);
formData.append('username', 'player123');

const res = await fetch('https://www.topdofus.com/api/vote/init', {
    method: 'POST',
    body: formData,
});
const data = await res.json();

if (data.success) {
    window.location.href = data.vote_url;
}

// Step 2: Verify vote
const verifyData = new FormData();
verifyData.append('api_key', API_KEY);
verifyData.append('token', data.token);

const verify = await fetch('https://www.topdofus.com/api/vote/verify', {
    method: 'POST',
    body: verifyData,
});
const result = await verify.json();

if (result.success && result.voted) {
    console.log('Vote confirmed!');
}

Python

import requests

API_KEY   = 'YOUR_API_KEY'
SERVER_ID = 1

# Step 1: Init vote
res = requests.post('https://www.topdofus.com/api/vote/init', data={
    'api_key': API_KEY,
    'server_id': SERVER_ID,
    'username': 'player123',
})
data = res.json()

if data['success']:
    vote_url = data['vote_url']
    # Redirect user to vote_url

# Step 2: Verify vote
verify = requests.post('https://www.topdofus.com/api/vote/verify', data={
    'api_key': API_KEY,
    'token': data['token'],
})
result = verify.json()

if result['success'] and result['voted']:
    print('Vote confirmed! Reward the player.')

HTTP Status Codes

Important Notes

• Each IP can only vote once every 12 hours per server.
• Tokens expire after 30 minutes if not used.
• The voter's IP is recorded to prevent abuse.
• Always use HTTPS for API requests in production.