Desenvolvedores · API v1

Integre a reputação TopV
no seu site, Tebex, Discord.

API pública gratuita. Badges SVG embutíveis. JSON com CORS aberto. Sem chave, sem cadastro, sem rate-limit punitivo.

Badges SVG

Embutíveis via <img>. 8 variantes de cor, auto-match com o design do seu site.

API JSON

CORS * aberto. Nenhuma chave necessária. Cache CDN + stale-while-revalidate.

Estável

Endpoints versionados (/api/v1/*). Rate-limit razoável, 429 com Retry-After se excedido.

Início rápido

Badges SVG

HTML

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

Widget de voto 400×80 com botão. Para homepage de store.

HTML

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

API JSON

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}

Badge SVG 160×32 (criador). ?color= aceito.

SVG

GET

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

Badge SVG 160×32 (servidor FiveM/RedM).

SVG

GET

/api/v1/widget/{slug}

Widget de voto 400×80 com botão. Para homepage de store.

SVG

GET

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

Widget de voto para servidor.

SVG

GET

/api/v1/creator/{slug}

Dados completos do criador: votos, rating, reviews, tier, links.

JSON

GET

/api/v1/server/{slug}

Dados completos do servidor.

JSON

GET

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

Top N ranking por votos.

JSON

GET

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

Pesquisa de texto completo (mín. 2 caracteres).

JSON

Parâmetros de badge e widget

?color=

Força uma das 8 variantes disponíveis. Se ausente, a cor auto-match com o accent do perfil TopV.

orange

red

rose

coral

gold

violet

sky

mint

Limites de taxa

Badge / widget SVG

300 req/min por IP.

JSON creator / server / search

60 req/min por IP.

JSON rankings

30 req/min por IP (join + sort, mais caro).

Em caso de excedência: resposta 429 Too Many Requests · Retry-After: 60

Versionamento

Use /api/v1/* para compatibilidade de longo prazo. Endpoints legados (/api/badge/*, /api/widget/*, /api/public/*) permanecem funcionais mas podem evoluir. Em caso de breaking change, um novo /api/v2 será introduzido — v1 permanecerá intacto.

Você é criador TopV?

O código para copiar e colar no seu site já está pré-gerado no seu dashboard, com seu slug pré-preenchido e as 8 variantes de cor em pré-visualização ao vivo.

Abrir meu dashboard de Widgets