Badgen API
Free badge API with no key: build shields-style SVG badges from a URL path. Static badges, live data badges and custom colours. Tested example and live response.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the Badgen API?
Badgen is a free, key-free API that generates SVG status badges from a URL. Requesting a path of the form `/badge/label/status/color` returns a ready-to-embed SVG badge, and dedicated paths render live badges for npm, GitHub, Docker Hub and other services.
Badges are the small coloured labels at the top of nearly every README — build passing, version 2.1.0, coverage 94%. Badgen generates them as SVG from nothing but a URL, so adding one to a README is a single Markdown image line with no build step, no account and no key.
It is a faster, lighter alternative to the more familiar shields.io, with the same URL grammar for static badges. The static form is fully deterministic — label, status and colour all come from the path — which makes it trivial to generate badges programmatically from a CI job. Live badges that query a third-party service are also available, and those are cached by Badgen for a few minutes.
Quick facts
- Base URL
https://badgen.net- Authentication
- No API key or account. Live badges for private repositories are not supported, since Badgen has no credentials of yours.
- Rate limit
- No published limit for static badges, which are generated without any upstream call.
- Pricing
- Free and open source (ISC licence).
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the Badgen API
Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.
1. Generate a green 'tested: passing' badge
GET https://badgen.net/badge/tested/passing/green
curl 'https://badgen.net/badge/tested/passing/green'const res = await fetch("https://badgen.net/badge/tested/passing/green");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://badgen.net/badge/tested/passing/green", timeout=20)
res.raise_for_status()
print(res.json())<svg width="96.2" height="20" viewBox="0 0 962 200" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="tested: passing">
<title>tested: passing</title>
<linearGradient id="lsOyL" x2="0" y2="100%">
<stop offset="0" stop-opacity=".1" stop-color="#EEE"/>
<stop offset="1" stop-opacity=".1"/>
</linearGradient>
<mask id="MuJVz"><rect width="962" height="200" rx="30" fill="#FFF"/><Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
label | path segment | Required | Left-hand text of the badge. Use a hyphen for a space and a doubled hyphen for a literal dash. tested |
status | path segment | Required | Right-hand text of the badge. passing |
color | path segment | Optional | Named colour (`green`, `blue`, `red`, `orange`, `grey`) or a bare hex value without the leading hash. Defaults to blue. green |
icon | query | Optional | Adds an icon from Badgen's built-in set, for example `github` or `npm`. github |
labelColor | query | Optional | Overrides the colour of the left-hand section. black |
scale | query | Optional | Size multiplier for the rendered SVG. Defaults to 1. 1.5 |
Response fields
(body)svg- The badge as SVG markup, served with `Content-Type: image/svg+xml`. Includes an `aria-label` matching the badge text, so it is accessible when embedded.
width / heightattribute- Computed from the text length, so badges size themselves automatically.
What you can build with the Badgen API
- Add build, version or coverage badges to a README
- Generate a status badge from a CI job and commit it alongside the docs
- Show a live npm download count or GitHub star count in project docs
- Build a small internal status board out of static badge URLs
Common errors and how to fix them
404
Unknown badge type in the first path segment.
Fix: For a static badge the path must start with `/badge/`. Live badge types have their own prefixes such as `/npm/` or `/github/`.
200 with 'unknown' text
A live badge could not reach its upstream service or the target does not exist.
Fix: Verify the package or repository name; Badgen renders the failure into the badge rather than returning an error status.
Badgen API — frequently asked questions
Is the Badgen API free and does it need a key?
Yes, it is free with no API key and no account. Badgen is open source under the ISC licence and can be self-hosted on any serverless platform if you want your own instance.
How is Badgen different from shields.io?
It uses the same URL grammar for static badges but is a lighter, faster implementation with fewer live-data integrations. For a plain label, status and colour badge the two are interchangeable.
How do I put a space in a Badgen label?
Use a hyphen — `build-status` renders as "build status". A literal hyphen needs to be doubled, so `well--tested` renders as "well-tested".
Can Badgen show badges for a private repository?
No. Badgen has no access to your credentials, so live badges only work against publicly readable data. For private projects, generate a static badge in CI where you already hold the numbers.
Tools that pair with this API
SVG to PNG Converter
Convert SVG vector files to PNG at any resolution you choose. Render crisp raster images from SVG in your browser — free, instant and private.
Color Picker from Image
Pick colors from any image online. Click a photo to get exact HEX, RGB and HSL values with copy buttons and a history of recent picks — free and private.
Markdown to HTML Converter
Convert Markdown to clean HTML with a live preview — headings, emphasis, links, lists, code blocks, tables and blockquotes. 100% in your browser.
Badgen is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.