API Reference

URL format

https://shieldcn.dev/{provider}/{...params}.svg

https://shieldcn.dev/{provider}/{...params}.png

https://shieldcn.dev/{provider}/{...params}.json

https://shieldcn.dev/{provider}/{...params}/shields.json

Badge endpoints

npm

GitHub

Views

Stateful view counters — the count increments on every render and the response is served uncached (Cache-Control: no-store). Use ?base=N to add an existing total when migrating from another counter (the base is added at render, never stored, and must stay in the URL).

Discord

NBA

{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

Static badges — no API token required.

Homebrew

Tokscale

skills.sh

Country Flags

{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

Join any badge paths with +. Query params apply to all segments. See Badge Group docs.

Static

Charts

Shadcn-styled line/area charts. Support mode, theme, color, fill, area, bg, border, font, width, height, title, days (npm), and values/dates/labels or url/query (JSON). See Charts docs.

Headers

Premade backgrounds: surface, gradient, dots, grid, graph, glow, transparent. Support title, subtitle, logo, logoColor, size (banner, wide, social, square), width, height, align, bg, gradient, glow, accent, titleColor, subtitleColor, radius, border, watermark, pattern, plus mode, theme, and font. See Headers docs.

Sponsors

A grid of an account's active public GitHub Sponsors. Arrange tiers by pinning logins with special and backers (comma-separated). Support specialTitle, sponsorsTitle, backersTitle, title, size, width, limit, names, bg, accent, radius, border, watermark, plus mode and font. See Sponsors docs.

Contributors

A contrib.rocks-style grid of a repository's top contributors, ordered by contributions. Bots are excluded by default (bots=true to include). Supports title, limit, min, names, size, width, align, titleAlign, the full header background system (preset, theme, bg, gradient, pattern, glow, image, overlay, tint, accent), radius, border, watermark, plus mode and font. See Contributors docs.

Query parameters

Response formats

PNG

Content-Type: image/png
Cache-Control: public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400

PNG 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

Content-Type: image/svg+xml
Cache-Control: public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400

SVG badges are scalable and have smaller file sizes. Use .svg when you need crisp rendering at any scale.

JSON

{
  "label": "npm",
  "value": "v19.1.0",
  "color": "blue",
  "link": "https://www.npmjs.com/package/react"
}

Shields.io compatible

{
  "schemaVersion": 1,
  "label": "npm",
  "message": "v19.1.0",
  "color": "blue"
}

Use with shields.io endpoint badge:

![npm](https://img.shields.io/endpoint?url=https://shieldcn.dev/npm/react/shields.json)