BYTETOOLS

Shields.io API

Free badge API with no key: generate SVG status badges for READMEs from a URL, with custom labels, colours, logos and live data from 100+ services. Tested.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-19

What is the Shields.io API?

Shields.io is a free, key-free API that generates SVG status badges from a URL. It produces the version, build status and licence badges seen at the top of most GitHub READMEs, with custom labels, colours and logos.

Shields.io badges are built entirely from the URL — label, message and colour are path segments, so a badge needs no configuration and no account. Requesting `.json` instead of `.svg` returns the badge data as JSON, which is what the verified example here shows.

Beyond static badges, it has integrations with over a hundred services that fetch live data: npm version, build status, download counts, licence. Those dynamic badges are cached, so a change upstream takes a few minutes to appear.

Quick facts

Base URL
https://img.shields.io
Authentication
No API key required. Some service integrations accept optional tokens to raise upstream rate limits.
Rate limit
No published limit; badges are heavily CDN-cached.
Pricing
Free and open source.
CORS
Enabled — callable directly from browser JavaScript
Official docs
Read the docs

How to use the Shields.io API

Every request below was executed against the live API on 2026-08-19, and the response shown is the real body it returned — not an illustration.

1. Generate badge data as JSON

GET https://img.shields.io/badge/tested-passing-green.json

curl
curl 'https://img.shields.io/badge/tested-passing-green.json'
JavaScript (fetch)
const res = await fetch("https://img.shields.io/badge/tested-passing-green.json");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);
Python (requests)
import requests

res = requests.get("https://img.shields.io/badge/tested-passing-green.json", timeout=20)
res.raise_for_status()
print(res.json())
Response — HTTP 200
{
  "label": "tested",
  "message": "passing",
  "color": "green",
  "link": [],
  "name": "tested",
  "value": "passing"
}

Parameters

ParameterTypeRequiredDescription
badge/<label>-<message>-<color>pathRequiredStatic badge content; hyphens separate the three parts. tested-passing-green
stylestringOptionalflat, flat-square, plastic, for-the-badge or social. flat-square
logostringOptionalSimple Icons slug to show a logo. github
labelColor / colorstringOptionalOverride the left and right colours. blue
cacheSecondsintegerOptionalMinimum cache duration for dynamic badges. 3600

Response fields

(SVG image)image
The default response is an SVG badge, embeddable directly in Markdown.
labelstring
On the .json variant, the left-hand text.
messagestring
The right-hand text.
colorstring
Badge colour.

What you can build with the Shields.io API

  • Add build, version and licence badges to a README
  • Generate custom status badges for internal dashboards
  • Show live npm or PyPI version numbers automatically
  • Produce consistent badge styling across a set of repositories

Common errors and how to fix them

Badge shows 'invalid'

The dynamic badge could not reach or parse the upstream service.

Fix: Check the underlying service is reachable and the parameters are correct; static badges never show this.

Hyphen in the label breaks the badge

Hyphens are the separator in the badge path.

Fix: Escape a literal hyphen by doubling it, and encode spaces as underscores or %20.

Badge does not update

Dynamic badges are cached.

Fix: Wait for the cache to expire, or set cacheSeconds — you cannot force an immediate refresh.

Shields.io API — frequently asked questions

Is Shields.io free?

Yes, completely free and open source with no API key required. It is one of the most widely used services on GitHub.

How do I make a custom badge?

Use /badge/<label>-<message>-<color>.svg. For example /badge/tested-passing-green.svg produces a green 'tested | passing' badge.

How do I put a literal hyphen in a badge?

Double it. A single hyphen separates label, message and colour, so `--` renders as one hyphen.

Why doesn't my badge update immediately?

Dynamic badges are cached to protect upstream services. Changes take a few minutes to appear, and you can influence but not bypass this with cacheSeconds.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

URL Encoder

Percent-encode text for URLs instantly. Switch between encodeURIComponent and encodeURI modes, see live output and copy the result. Free URL encoder.

Shields.io is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-19; always check the official documentation before relying on this API in production, as terms and limits can change.