Everything the SVG badge API understands.

Query and path endpoints, eleven rendering styles including three fixed-size classics with auto-scaling vector text, exact 50–300% sizing, adjustable letter spacing, four color controls, Unicode-aware width, immutable cache headers, ETags, and practical examples.

Overview

Tiny Badge returns a deterministic SVG image from the label, message, style, size, letter spacing, and colors encoded in the request URL. Unicode graphemes are measured with go-runewidth and UAX #29 segmentation, successful responses use long-lived immutable caching and content-derived ETags, and the same URL always describes the same badge.

Production origin https://badge-api.gosuda.org

Every example on this page is ready to use against the live Tiny Badge service.

Endpoints

Query endpoint

Use query parameters when text contains spaces, punctuation, or a literal .svg suffix.

GET /badge.svg
HEAD /badge.svg

https://badge-api.gosuda.org/badge.svg?label=build&message=passing&style=flatbar&size=125&letterSpacing=0.5

Path endpoint

Use the shorter path form for simple label and message values.

GET /badge/:label/:message
HEAD /badge/:label/:message

https://badge-api.gosuda.org/badge/release/stable.svg

Use _ as the path label for a badge without a left segment.

/badge/_/available.svg

The path form removes a final .svg suffix. The query form preserves it.

Parameters

messageRequired

Main badge text. Maximum 128 characters.

Default: —

labelOptional

Left-side badge text. Maximum 64 characters.

Default: Empty

styleOptional

Selects one of the eleven rendering styles.

Default: flat

sizeOptional

Scales the whole badge from 50 to 300 percent. Integer values only.

Default: 100

letterSpacingOptional

Adds -1 to 3 SVG pixels between grapheme clusters. Decimal values are accepted.

Default: 0

labelColorOptional

Background color for the label segment.

Default: 555555

colorOptional

Background color for the message segment.

Default: 44cc11

labelTextColorOptional

Text color for the label segment.

Default: ffffff

textColorOptional

Text color for the message segment.

Default: ffffff

Spaces and punctuation must be URL encoded. For example, ready to ship becomes ready%20to%20ship.

letterSpacing is measured in SVG user units: one unit is one output pixel at 100% scale. Nonzero spacing replaces the fixed word artwork in matching click-here and best-viewed reference phrases with adjustable vector text.

Styles

`flat`

20 px, gently rounded, and the default.

`flat-square`

The flat style with square corners.

`plastic`

A compact badge with a highlight layer.

`round`

A taller capsule with fully rounded ends.

`outline`

A framed surface with a brighter inner edge.

`neon`

A focused glow around each color segment.

`glass`

A layered sheen with a quiet border.

`flatbar`

A 28 px uppercase bar inspired by larger badge styles.

`old-school`

Old School 80×15: a fixed split-panel button with customizable colors and resolution-independent text that automatically shrinks to fit each panel.

`click-here`

Click Here 88×31: the supplied raised gray artwork for its reference phrase, with high-resolution auto-fit vector text for custom copy.

`best-viewed`

Best Viewed 88×31: the supplied BEST rail and Chrome artwork, with separately auto-scaled vector text for both custom lines.

Colors

The API uses 3-digit or 6-digit hexadecimal values without the leading #.

labelColor=292724&color=d6ef53&labelTextColor=ffffff&textColor=292724

The maker keeps colors internally as RGB. Hex, HSL, and OKLCH channel inputs are converted to RGB before the URL is assembled.

If a leading # is included, encode it as %23 so it does not become a URL fragment.

Named colors

brightgreengreenyellowgreenyelloworangeredbluegreygraylightgreylightgraysuccessimportantcriticalinformationalinactive

Examples

Markdown

![Build status](https://badge-api.gosuda.org/badge.svg?label=build&message=passing)

HTML

<img src="https://badge-api.gosuda.org/badge.svg?label=build&message=passing" alt="Build: passing">

cURL

curl -o badge.svg 'https://badge-api.gosuda.org/badge.svg?label=build&message=passing&style=flatbar'

Responses and caching

Successful requests return an SVG image with long-lived immutable caching and a content-derived ETag.

Content-Type: image/svg+xml; charset=utf-8
Cache-Control: public, max-age=315360000, immutable
CDN-Cache-Control: public, max-age=315360000, immutable
Surrogate-Control: public, max-age=315360000, immutable
Access-Control-Allow-Origin: *
ETag: "<content hash>"

Send the ETag in If-None-Match. An unchanged badge returns 304 Not Modified without a response body.

Errors and limits

Invalid input returns 400 Bad Request with Cache-Control: no-store.

message

Required and limited to 128 characters.

label

Optional and limited to 64 characters.

style

Must match one of the documented style names.

size

Must be an integer percentage from 50 through 300.

letterSpacing

Must be a decimal number from -1 through 3.

colors

Must be a supported name or a 3-digit or 6-digit hex value.

Health check

GET /healthz → 200 OK → ok