API Reference
Complete URL specification, query parameters, and response formats.
URL format
All endpoints support both
.svg and .png — swap .json to get raw badge data, or append /shields.json for shields.io compatibility. Use SVG by default for the crispest rendering.https://shieldcn.dev/{provider}/{...params}.svghttps://shieldcn.dev/{provider}/{...params}.pnghttps://shieldcn.dev/{provider}/{...params}.jsonhttps://shieldcn.dev/{provider}/{...params}/shields.jsonBadge endpoints
npm
| Endpoint | Description |
|---|---|
/npm/{package}.svg | Latest version |
/npm/{package}/downloads.svg | Weekly download count |
/npm/@scope/package.svg | Scoped package version |
GitHub
| Endpoint | Description |
|---|---|
/github/{owner}/{repo}/stars.svg | Star count |
/github/{owner}/{repo}/release.svg | Latest release tag |
/github/{owner}/{repo}/ci.svg | CI workflow status |
/github/{owner}/{repo}/license.svg | SPDX license identifier |
/github/downloads/{owner}/{repo}.svg | Downloads — all assets, all releases |
/github/downloads/{owner}/{repo}/latest.svg | Downloads — all assets, latest release |
/github/downloads/{owner}/{repo}/{tag}.svg | Downloads — all assets, specific tag |
/github/downloads-asset/{owner}/{repo}/{asset}.svg | Downloads — specific asset, all releases |
/github/downloads-asset/{owner}/{repo}/{asset}/latest.svg | Downloads — specific asset, latest release |
/github/downloads-asset/{owner}/{repo}/{asset}/{tag}.svg | Downloads — specific asset, specific tag |
Discord
| Endpoint | Description |
|---|---|
/discord/{serverId}.svg | Online member count |
/discord/members/{inviteCode}.svg | Approximate member count from invite |
/discord/online-members/{inviteCode}.svg | Approximate online member count from invite |
NBA
| Endpoint | Description |
|---|---|
/nba.svg | Default “2026 champs / Knicks” badge using the branded Knicks color |
/nba/{team}.svg | NBA team fan badge with team logo and team color |
{team} accepts common team slugs, names, abbreviations, and nicknames such as knicks, ny, celtics, bos, warriors, and gs. Omit {team} for the default “2026 champs / Knicks” badge. See NBA docs.
X / Twitter
| Endpoint | Description |
|---|---|
/x/{username}.svg | Follow CTA (default) |
/x/follow/{username}.svg | "follow @username" CTA |
/x/mention/{username}.svg | "@username" mention CTA |
Static badges — no API token required.
Homebrew
| Endpoint | Description |
|---|---|
/homebrew/{formula}.svg | Formula version |
/homebrew/cask/{cask}.svg | Cask version |
/homebrew/dm/{formula}.svg | Formula downloads (monthly) |
/homebrew/dq/{formula}.svg | Formula downloads (quarterly) |
/homebrew/dy/{formula}.svg | Formula downloads (yearly) |
/homebrew/cask-dm/{cask}.svg | Cask downloads (monthly) |
/homebrew/cask-dq/{cask}.svg | Cask downloads (quarterly) |
/homebrew/cask-dy/{cask}.svg | Cask downloads (yearly) |
Tokscale
| Endpoint | Description |
|---|---|
/tokscale/{username}.svg | Total token count (default) |
/tokscale/tokens/{username}.svg | Total token count |
/tokscale/cost/{username}.svg | Estimated total cost |
/tokscale/rank/{username}.svg | Global leaderboard rank |
/tokscale/active-days/{username}.svg | Days with AI activity |
/tokscale/stats.svg | Global user count |
skills.sh
| Endpoint | Description |
|---|---|
/skills/{owner}/{repo}/{skill}.svg | All-time install count (default) |
/skills/installs/{owner}/{repo}/{skill}.svg | All-time install count |
/skills/rank/{owner}/{repo}/{skill}.svg | All-time leaderboard rank |
/skills/trending/{owner}/{repo}/{skill}.svg | Trending leaderboard rank |
/skills/hot/{owner}/{repo}/{skill}.svg | Hot (last 24h) leaderboard rank |
Country Flags
| Endpoint | Description |
|---|---|
/flag/{code}.svg | “built in country” with a flag chip |
{code} is an ISO 3166-1 alpha-2 country code (case-insensitive), plus regions
and subdivisions like eu, gb-eng, es-ct. 265 codes supported. Definite
articles are applied automatically (us → “the USA”). See Country Flags docs.
Badge Group
| Endpoint | Description |
|---|---|
/group/{badge1}+{badge2}+{badge3}.svg | Multiple badges joined in one image |
Join any badge paths with +. Query params apply to all segments. See Badge Group docs.
Static
| Endpoint | Description |
|---|---|
/badge/{label}-{message}-{color}.svg | Custom text badge |
/badge/dynamic/json.svg?url=...&query=... | Dynamic JSON badge |
Query parameters
Appearance
PropType
Colors
PropType
Icons
PropType
Layout
PropType
Effects
PropType
Animation is SVG-only and works inside GitHub's image sandbox because it uses pure CSS keyframes — no JavaScript.
pulse and glow require a status dot (auto for CI badges, or set statusDot=true with a color).Response formats
PNG
http
Content-Type: image/png
Cache-Control: public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400PNG badges are rasterized at exact badge dimensions. Use SVG when you want the crispest badge rendering; use PNG only where SVG is not accepted.
SVG
http
Content-Type: image/svg+xml
Cache-Control: public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400SVG badges are scalable and have smaller file sizes. Use .svg when you need crisp rendering at any scale.
JSON
json
{
"label": "npm",
"value": "v19.1.0",
"color": "blue",
"link": "https://www.npmjs.com/package/react"
}Shields.io compatible
json
{
"schemaVersion": 1,
"label": "npm",
"message": "v19.1.0",
"color": "blue"
}Use with shields.io endpoint badge:
