TopSites: API

The directory is readable through the standard XenForo REST API, and a listing's owner can additionally read that listing's votes. Same base path, same authentication, same error shape as the rest of the forum.

Contents

• Checking a single voter
• Push or pull: choosing an integration
• Worked example: an in-game vote reward button
• Caching and rate limits
• Errors

Your listing key

Everything on this page uses one key, and it is yours: you generate it on your own listing, no staff involvement, and it works for that listing only. Treat it like a password - anyone holding it can ask whether a given member voted for you.

Getting your listing key

1. Open your listing and press Manage listing.
2. Go to the Rewards tab.
3. Next to Listing key, press Generate key.

Copy it somewhere safe. Treat it like a password: anyone holding it can ask whether a given member voted for your listing.

Using it

Send it as a header, or as a query parameter if your game server can only manage a URL:

# header (preferred - stays out of access logs)
curl -H 'RZ-Listing-Key: YOUR_LISTING_KEY' \
  'https://forum.ragezone.com/topsites/51/vote-check?user_id=12'

# query parameter
curl 'https://forum.ragezone.com/topsites/51/vote-check?key=YOUR_LISTING_KEY&user_id=12'

Checking a single voter

The endpoint most reward integrations actually want. One player, one answer, using your listing key.

GET https://forum.ragezone.com/topsites/{listing_id}/vote-check

{
    "content_id": 51,
    "user_id": 12,
    "period": "2026-08",
    "voted": true,
    "vote_date": 1787416627,
    "vote_source": "site"
}

voted is the answer; the rest is context. A withdrawn vote returns false.

Push or pull: choosing an integration

There are two ways to reward a voter, and they are not mutually exclusive.

Worked example: an in-game vote reward button

The player clicks "claim vote reward" on your website, in your launcher, or via an in-game command. Your server does this:

<?php

const RZ_BASE   = 'https://forum.ragezone.com';
const RZ_KEY    = 'your-listing-key';
const RZ_ITEM   = 51;              // your listing id

/**
 * Ask whether this forum member has voted for us this period.
 */
function hasVoted(int $forumUserId): bool
{
    $url = RZ_BASE . '/topsites/' . RZ_ITEM . '/vote-check?user_id=' . $forumUserId;

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['RZ-Listing-Key: ' . RZ_KEY],
        CURLOPT_TIMEOUT        => 5,
    ]);

    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code !== 200) {
        // Never fail open. If you cannot confirm the vote, do not pay out.
        error_log('rz vote-check failed: HTTP ' . $code);
        return false;
    }

    $data = json_decode($body, true);

    return !empty($data['voted']);
}

/**
 * Claim, once per period. The unique key does the work - two clicks in the
 * same second cannot both win.
 */
function claimVoteReward(PDO $db, int $gameAccountId, int $forumUserId): string
{
    $period = gmdate('Y-m');   // must be UTC, to match the vote period

    if (!hasVoted($forumUserId)) {
        return 'not_voted';
    }

    $stmt = $db->prepare(
        'INSERT IGNORE INTO vote_rewards (forum_user_id, vote_period, rewarded_at)
         VALUES (?, ?, ?)'
    );
    $stmt->execute([$forumUserId, $period, time()]);

    if ($stmt->rowCount() === 0) {
        return 'already_claimed';
    }

    $db->prepare('UPDATE accounts SET vote_points = vote_points + 1 WHERE id = ?')
       ->execute([$gameAccountId]);

    return 'granted';
}

The same vote_rewards table serves both integrations, so a player who was already rewarded by the callback gets already_claimed rather than a second payout. That shared table is the whole trick.

Showing the player where they stand

$period = gmdate('Y-m');

$stmt = $db->prepare('SELECT rewarded_at FROM vote_rewards WHERE forum_user_id = ? AND vote_period = ?');
$stmt->execute([$forumUserId, $period]);

if ($stmt->fetchColumn()) {
    $message = 'You have claimed this month. Next reward on the 1st.';
} else {
    $message = 'Vote now to claim this month’s reward.';
}

Caching and rate limits

• Do not poll vote-check on a timer. Call it when a player asks. A loop over every account is the fastest way to get a key revoked.
• Cache a positive answer. Once voted is true for a period it stays true unless the voter withdraws. Store it and stop asking.
• Use /votes for reconciliation, not for live checks. One call after an outage beats a thousand individual lookups.
• Set a short timeout - 5 seconds is plenty - and fail closed. A player waiting on a spinner is better than a player getting a free reward because your check timed out.

Errors

Standard XenForo shape:

{ "errors": [ { "code": "...", "message": "...", "params": [] } ] }

What the API deliberately does not do

• No writing. Listings are managed through the site.
• No voting with a key. No API key can cast a vote - a key that could would be a vote-stuffing tool with a support contract. The public vote endpoint below is a different thing: it takes no key at all and counts the player's own device as the voter, which is what keeps it honest.
• No reading other people's voters. Ownership is enforced on every vote endpoint.