API Documentation

Voting API

Check a recent vote by IP address or username within the server vote interval. When no recent vote exists, the API returns HTTP 404 with success set to false and the message User not voted. Username lookup does not prove identity and returns null for ipv4 and ipv6.

Endpoint	https://private-server.net/en/api/v1/servers/{server_token}/votes/{identifier}
{server_token}	Indicate the Token associated with your server. You can find it in the 'Settings' tab
{identifier}	IPv4, IPv6 or a username of 3 to 32 ASCII letters, digits, hyphens, dots or underscores. Example: /votes/Trevor. URL-encode this value.
?type=username	Optional: forces username lookup when the username looks like an IP address. Example: /votes/1.2.3.4?type=username. Without this parameter, valid IP addresses retain their existing behavior.

Code Example

<?php
$server_token = "Your server token"; // Replace "TOKEN" with your server token.
$identifier = "Trevor";
$query_url = "https://private-server.net/en/api/v1/servers/$server_token/votes/" . rawurlencode($identifier);
$context = stream_context_create(["http" => ["ignore_errors" => true]]);
$json = file_get_contents($query_url, false, $context);
$json_data = json_decode($json);
if ($json_data->success) {
    echo 'You have successfully voted';
    // You can use the following variables:
    $datas = $json_data->data; // This variable will contain the JSON data returned by the API.
    $datas->username; // User's username
    $datas->voted_at; // Corresponds to the voting date in timestamp format
    $datas->is_connected; // Corresponds to the user's connection status
    $datas->is_subscriber; // Corresponds to the user's subscription status
    $datas->next_vote_seconds; // Corresponds to the number of seconds remaining before the user can vote again
} else {
    echo 'No or already voted';
}
?>

Response Example

{
    "success": true,
    "data": {
        "username": "Trevor",
        "ipv4": null,
        "ipv6": null,
        "voted_at": 1689241974,
        "next_vote_seconds": 5395,
        "is_connected": true,
        "is_subscriber": false
    }
}

Statistics API

Allows you to retrieve data about your server such as its position, number of votes, etc.

Endpoint	https://private-server.net/en/api/v1/servers/{server_token}/statistics
{server_token}	Indicate the Token associated with your server. You can find it in the 'Settings' tab

Code Example

<?php
$server_token = "Your server token"; // Replace "TOKEN" with your server token.
$json = file_get_contents("https://serveur-prive.net/api/v1/servers/$server_token/statistics");
$json_data = json_decode($json);
if ($json_data->success) {
    echo 'Server found';
    // You can use the following variables:
    $datas = $json_data->data; // This variable will contain the JSON data returned by the API.
    $datas->position; // Corresponds to the server's position in the monthly ranking
    $datas->votes_count; // Corresponds to the number of votes for the server
    $datas->clicks_count; // Corresponds to the number of clicks on the server
    $datas->comments_count; // Corresponds to the number of comments on the server
    $datas->rating; // Corresponds to the server's rating out of 5
} else {
    echo 'The specified Token is incorrect';
}
?>

Response Example

{
    "success": true,
    "data": {
        "position": 12,
        "votes_count": 1202,
        "clicks_count": 287,
        "comments_count": 7,
        "rating": 5
    }
}

Donors API

Allows you to retrieve users who have donated to your server from the donation page

Endpoint	https://private-server.net/en/api/v1/servers/{server_token}/donors
{server_token}	Indicate the Token associated with your server. You can find it in the 'Settings' tab

Code Example

<?php
$server_token = "Your server token"; // Replace "TOKEN" with your server token.
$json = file_get_contents("https://serveur-prive.net/api/v1/servers/$server_token/donors");
$json_data = json_decode($json);
if ($json_data->success) {
    echo 'Server found';
    // You can use the following variables:
    $datas = $json_data->data; // This variable will contain the JSON data returned by the API.
    foreach($datas as $data) {
        $data->username; // Donor's username
        $data->avatar; // Corresponds to the donor's or subscriber's avatar
        $data->amount; // Corresponds to the amount donated
        $data->message; // Corresponds to the donor's message
        $data->currency; // Corresponds to the currency of the donation
        $data->created_at; // Corresponds to the date of the donation in timestamp format
    }
} else {
    echo 'The specified Token is incorrect';
}
?>

Response Example

{
    "success": true,
    "data": [{
        "username": "Trevor",
        "avatar": "url",
        "amount": 10,
        "message": "Message...",
        "currency": "eur",
        "created_at": 1689241974
    }]
}

Subscribers API

API to retrieve users who have subscribed to your server from the voting page

Endpoint	https://private-server.net/en/api/v1/servers/{server_token}/subscribers
{server_token}	Indicate the Token associated with your server. You can find it in the 'Settings' tab

Code Example

<?php
$server_token = "Your server token"; // Replace "TOKEN" with your server token.
$json = file_get_contents("https://serveur-prive.net/api/v1/servers/$server_token/subscribers");
$json_data = json_decode($json);
if ($json_data->success) {
    echo 'Server found';
    // You can use the following variables:
    $datas = $json_data->data; // This variable will contain the JSON data returned by the API.
    foreach($datas as $data) {
        $data->username; // Subscriber's username
        $data->avatar; // Corresponds to the subscriber's avatar
        $data->started_at; // Corresponds to the start date of the subscription in timestamp format
        $data->ended_at; // Corresponds to the end date of the subscription in timestamp format
    }
} else {
    echo 'The specified Token is incorrect';
}
?>

Response Example

{
    "success": true,
    "data": [{
        "username": "Trevor",
        "avatar": "url",
        "started_at": 1689241974,
        "ended_at": 1689241974
    }]
}

Top Voters API

Allows you to retrieve the list of users who have voted for your server over the month

Endpoint	https://private-server.net/en/api/v1/servers/{server_token}/voters
{server_token}	Indicate the Token associated with your server. You can find it in the 'Settings' tab

Code Example

<?php
$server_token = "Your server token"; // Replace "TOKEN" with your server token.
$json = file_get_contents("https://serveur-prive.net/api/v1/servers/$server_token/voters");
$json_data = json_decode($json);
if ($json_data->success) {
    echo 'Server found';
    // You can use the following variables:
    $datas = $json_data->data; // This variable will contain the JSON data returned by the API.
    foreach($datas as $data) {
        $data->username; // Voter's username
        $data->position; // Corresponds to the server's position in the monthly ranking
        $data->votes; // Corresponds to the number of votes the player has
        $data->avatar; // Corresponds to the voter's avatar
        $data->subscribed; // Corresponds to the voter's subscription status
        $data->public_profile; // Corresponds to the URL of the voter's public profile
    }
} else {
    echo 'The specified Token is incorrect';
}
?>

Response Example

{
    "success": true,
    "data": [{
        "username": "Trevor",
        "position": 1,
        "votes": 10,
        "avatar": "url",
        "subscribed": true,
        "public_profile": "url",
    }]
}

OTP API (One-Time Token)

The API generates a unique temporary code valid for 5 minutes to authenticate each vote. This gives you full control over who can vote on your Serveur-Privé page, and no competitor can send artificial votes without going through your website and verification system.

Endpoint	https://private-server.net/en/api/v1/servers/{server_token}/otp
HTTP	GET
{server_token}	Indicate the Token associated with your server. You can find it in the 'Settings' tab
Validity Duration	The returned token expires after 300 seconds (5 minutes).

Code Example

<?php
$server_token = "Your server token"; // Replace "TOKEN" with your server token.
$json = file_get_contents("https://serveur-prive.net/api/v1/servers/$server_token/otp");
if ($json === false) {
    exit("API call failed");
}

$data = json_decode($json);
if (!empty($data->success)) {
    $otp = $data->data->token; // Example: Txg5tk32z6mX
    echo "OTP generated: $otp\n";
    echo "Vote link: https://serveur-prive.net/minecraft/{server-slug}/vote?otp=$otp";
} else {
    echo "OTP generation failed";
}
?>

Response Example

{
    "success": true,
    "data": {
        "token": "Txg5tk32z6mX",
        "message": "The code has been generated successfully. It will be valid for 5 minutes."
    }
}

OTP API → check by token

Checks the status of a One-Time Token (OTP) and returns whether it has been used for a valid vote. Use this endpoint after redirecting the user to your voting page with the token.

Endpoint	https://private-server.net/en/api/v1/servers/{server_token}/votes/otp/{token}
HTTP	GET
{server_token}	Indicate the Token associated with your server. You can find it in the 'Settings' tab
{token}	The OTP code previously generated using the OTP API. It is single-use and expires after a short period.

Code example

<?php
$server_token = "Your server token";
$token = $_GET["token"] ?? ""; // Retrieved from your voting flow

if ($token === "") {
    exit("Missing token");
}

$json = file_get_contents("https://serveur-prive.net/api/v1/servers/$server_token/votes/otp/$token");
if ($json === false) {
    exit("API call failed");
}

$json_data = json_decode($json);
if ($json_data->success) {
    echo 'You have successfully voted';
    // You can use the following variables:
    $datas = $json_data->data; // This variable will contain the JSON data returned by the API.
    $datas->username; // User's username
    $datas->voted_at; // Corresponds to the voting date in timestamp format
    $datas->is_connected; // Corresponds to the user's connection status
    $datas->is_subscriber; // Corresponds to the user's subscription status
    $datas->next_vote_seconds; // Corresponds to the number of seconds remaining before the user can vote again
} else {
    echo 'No or already voted';
}
?>

Example response

{
    "success": true,
    "data": {
        "username": "Trevor",
        "voted_at": 1689241974,
        "next_vote_seconds": 5395,
        "is_connected": true,
        "is_subscriber": false
    }
}