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 19 Aug 2026

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 19 Aug 2026, 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

Parameter	Type	Required	Description
`badge/<label>-<message>-<color>`	path	Required	Static badge content; hyphens separate the three parts. `tested-passing-green`
`style`	string	Optional	flat, flat-square, plastic, for-the-badge or social. `flat-square`
`logo`	string	Optional	Simple Icons slug to show a logo. `github`
`labelColor / color`	string	Optional	Override the left and right colours. `blue`
`cacheSeconds`	integer	Optional	Minimum 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.

Alternatives to Shields.io API

If Shields.io does not fit, these developer & testing apis cover similar ground. Every one was called before publishing, and each links to its own reference page with a working curl command and the response it returned.

API	What it does	Auth	CORS	Last verified
GitHub REST API	GitHub REST API with no key for public data: repository details, users, issues, releases and commits. 60 req/hour unauthenticated, 5,000 with a token.	No key	Yes	19 Aug 2026
JSONPlaceholder	Free fake REST API for testing and prototyping. Posts, comments, users and todos with full GET, POST, PUT and DELETE support. No key. Real curl examples.	No key	Yes	19 Aug 2026
Postman Echo	Postman Echo reflects your HTTP request back as JSON: headers, body, query params and auth. Free, no key, ideal for debugging clients. Real POST example.	No key	No	19 Aug 2026
DummyJSON	Free fake REST API with realistic products, users, carts, recipes and auth. Supports search, pagination, sorting and POST. No key. Tested GET and POST examples.	No key	Yes	19 Aug 2026
Simple Icons CDN	Fetch any brand's official SVG logo by slug, already coloured, with one GET request. No key, no npm install, permissive CORS. Verified example and sizing notes.	No key	Yes	21 Aug 2026
Snapcraft Store	Query the Snap Store for a package's channels, architectures, revisions and download URLs. No key, but one required header catches everyone out. Live example.	No key	No	21 Aug 2026

All Developer & Testing APIs

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