Developers · API v1

Integrate TopV reputation
into your site, Tebex, Discord.

Free public API. Embeddable SVG badges. JSON with open CORS. No key, no signup, no punitive rate-limit.

SVG Badges

Embeddable via <img>. 8 color variants, auto-match with your site's design.

JSON API

Open CORS *. No API key required. CDN cache + stale-while-revalidate.

Stable

Versioned endpoints (/api/v1/*). Reasonable rate-limit, 429 with Retry-After if exceeded.

Quick start

SVG Badges

HTML

<a href="https://topv.gg/creators/quasar-store">
  <img src="https://topv.gg/api/v1/badge/quasar-store" alt="TopV" />
</a>

Vote widget 400×80 with button. For store homepage.

HTML

<a href="https://topv.gg/creators/quasar-store">
  <img src="https://topv.gg/api/v1/widget/quasar-store" alt="Vote on TopV" />
</a>

JSON API

JavaScript

const res = await fetch("https://topv.gg/api/v1/creator/quasar-store");
const data = await res.json();
console.log(data.votes, data.rating, data.reviews);

Endpoints

GET

/api/v1/badge/{slug}

SVG badge 160×32 (creator). ?color= accepted.

SVG

GET

/api/v1/badge/server/{slug}

SVG badge 160×32 (FiveM/RedM server).

SVG

GET

/api/v1/widget/{slug}

Vote widget 400×80 with button. For store homepage.

SVG

GET

/api/v1/widget/server/{slug}

Server vote widget.

SVG

GET

/api/v1/creator/{slug}

Full creator data: votes, rating, reviews, tier, links.

JSON

GET

/api/v1/server/{slug}

Full server data.

JSON

GET

/api/v1/rankings?type=creators|servers&limit=10

Top N leaderboard by votes.

JSON

GET

/api/v1/search?q=query&type=creators|servers|all

Full-text search (min. 2 characters).

JSON

Badge & widget parameters

?color=

Force one of the 8 available variants. If absent, the color auto-matches the TopV profile's accent.

orange

red

rose

coral

gold

violet

sky

mint

Rate limits

Badge / widget SVG

300 req/min per IP.

JSON creator / server / search

60 req/min per IP.

JSON rankings

30 req/min per IP (join + sort, heavier).

On exceed: response 429 Too Many Requests · Retry-After: 60

Versioning

Use /api/v1/* for long-term compatibility. Legacy endpoints (/api/badge/*, /api/widget/*, /api/public/*) remain functional but may evolve. On breaking changes, a new /api/v2 will be introduced — v1 will stay intact.

Are you a TopV creator?

The code to copy-paste for your site is already pre-generated in your dashboard, with your slug pre-filled and the 8 color variants in live preview.

Open my Widgets dashboard