Vote API

API verejného hlasovania umožňuje tvojim integráciám čítať hlasy servera: získať zoznam hlasov, overiť, či konkrétny hráč hlasoval, a zobraziť štatistiky. Najčastejšie sa používa tak, že Discord bot pridelí hodnosť alebo odmenu tým, ktorí hlasovali.

Prístup je iba na čítanie — cez API nemôžeš hlasy meniť.

Získanie API kľúča

1. Otvor stránku svojho servera a dokonči overenie vlastníka.
2. V nastaveniach servera otvor sekciu „API keys” a klikni na „Create key”.
3. Skopíruj kľúč, ktorý vyzerá ako rsk_live_… — zobrazí sa iba raz. Ulož si ho ako heslo.

Kľúč môžeš obmedziť na jeden server alebo ho vydať pre všetky svoje servery. Skompromitovaný kľúč odvolaj v tej istej sekcii a vytvor nový.

Dôležité: nezverejňuj kľúč v open source kóde, repozitári ani vo verejne dostupnom configu bota. Ak kľúč unikne, odvolaj ho.

Základná URL a autorizácia

Základná URL: https://api.millida.net/v2/rating/api

Kľúč sa posiela v hlavičke X-Api-Key (alebo Authorization: Bearer …):

curl https://api.millida.net/v2/rating/api/stats \
  -H "X-Api-Key: rsk_live_YOUR_KEY"

Ak bol kľúč vydaný pre všetky servery nájomcu, pridaj do každej požiadavky parameter serverId. Pri kľúči viazanom na jeden server môžeš tento parameter vynechať.

Overenie hlasu hráča

Hlavný scenár pre Discord bota: „hlasoval tento človek”. Endpoint je GET /votes/check.

Parametre:

• discordId alebo nickname — koho overuješ (jeden z nich je povinný);
• since — obdobie: today (predvolené, od začiatku dňa v UTC) alebo počet hodín či dní — 24h, 7d, 30d;
• serverId — povinný, ak bol kľúč vydaný pre všetky servery.

curl "https://api.millida.net/v2/rating/api/votes/check?discordId=123456789012345678&since=today" \
  -H "X-Api-Key: rsk_live_YOUR_KEY"

Odpoveď:

{
  "voted": true,
  "serverId": "srv…",
  "voteId": "clx…",
  "votedAt": "2026-06-16T10:12:00.000Z",
  "discordId": "123456789012345678",
  "nickname": "Steve",
  "since": "2026-06-16T00:00:00.000Z"
}

Ak je voted true, hráč odovzdal započítaný hlas za zvolené obdobie. Započítavajú sa iba platné hlasy (botovanie a zamietnuté hlasy sa nepočítajú.)

O overovaní cez Discord: hlas sa prepojí s Discord účtom iba vtedy, ak ho hráč uviedol vo svojom Millida profile. Ak niektorí hráči nemajú prepojený Discord, overuj cez nickname alebo ich požiadaj, aby si Discord prepojili v profile.

Zoznam hlasov

GET /votes vracia hlasy servera od najnovších po najstaršie.

Parametre (všetky voliteľné):

• status — VALID, HELD, REJECTED_FRAUD, REJECTED_RATE_LIMIT, REJECTED_NO_PLAY_HISTORY alebo ALL (predvolene sa vrátia všetky);
• discordId, nickname — filter podľa hráča;
• from, to — rozsah dátumov vo formáte ISO;
• limit — koľko vrátiť (1–200, predvolene 50);
• cursor — kurzor ďalšej stránky z poľa nextCursor.

curl "https://api.millida.net/v2/rating/api/votes?status=VALID&limit=100" \
  -H "X-Api-Key: rsk_live_YOUR_KEY"

Odpoveď:

{
  "votes": [
    {
      "id": "clx…",
      "serverId": "srv…",
      "discordId": "123456789012345678",
      "nickname": "Steve",
      "status": "VALID",
      "votedAt": "2026-06-16T10:12:00.000Z"
    }
  ],
  "nextCursor": "eyJ…"
}

Ak chceš získať ďalšiu stránku, zopakuj požiadavku s cursor nastaveným na nextCursor. Keď je nextCursor null, ďalšie dáta už nie sú. IP adresy hlasujúcich sa cez API neposielajú.

Štatistiky

GET /stats vracia súhrnné počítadlá pre server:

{
  "serverId": "srv…",
  "validToday": 42,
  "valid24h": 50,
  "valid30d": 1280,
  "totalValid": 9001,
  "totalAll": 9500
}

Príklad: Discord bot pridelí rolu za hlasovanie

async function hasVotedToday(discordId) {
  const res = await fetch(
    `https://api.millida.net/v2/rating/api/votes/check?discordId=${discordId}&since=today`,
    { headers: { "X-Api-Key": process.env.MILLIDA_RATING_KEY } },
  );
  const data = await res.json();
  return data.voted === true;
}

Zavolaj túto funkciu pomocou Discord príkazu a pridel rolu, ak hráč hlasoval.

Obmedzenia

• API je iba na čítanie.
• Rýchlosť požiadaviek je obmedzená — to na overovanie na povel bohato stačí. Neopytuj API v tesnej slučke.
• Kľúč vidí iba hlasy z tvojich serverov.