Docs
Open Lodol
DocumentationIntegrationsAPI

Shields.io

App · Utilities · 7 actions

Generate dynamic SVG badges for your README, docs, or dashboards with Shields.io's keyless badge API. Build static 'subject | status' badges, version and license badges, dynamic badges that pull a live value from a JSON, XML, YAML, or TOML document or a regex match in any text file, endpoint badges driven by your own JSON, and any of the hundreds of ready-made service badges (GitHub stars, npm downloads, PyPI version, CI status). No account or API key required.

Actions

ActionWhat it does
Generate badgeCreate a static badge with a label, message, and color: the classic 'subject | status' badge.
Generate dynamic badgeCreate a badge whose message is pulled live from a remote JSON, XML, YAML, or TOML document.
Generate endpoint badgeCreate a badge from your own JSON endpoint.
Generate license badgeCreate a license badge, for example 'license | MIT'.
Generate regex badgeCreate a badge whose message is found by a regular expression in any remote text file: a README, a changelog, a config file.
Generate service badgeCreate any of Shields.io's ready-made service badges by its path: GitHub stars, npm downloads, PyPI version, Docker pulls, CI status, and hundreds more.
Generate version badgeCreate a version badge, for example 'Python | v3.8'.

Generate badge

Create a static badge with a label, message, and color: the classic 'subject | status' badge. Add a logo or a custom style to match your project's look.

Inputs

LabellabeltextRequired
Left-side text (the subject), for example 'build' or 'coverage'.
MessagemessagetextRequired
Right-side text (the status), for example 'passing' or '98%'.
Colorcolortext
Badge color: a named color (brightgreen, green, yellow, orange, red, blue, lightgrey, etc.) or a hex code such as 4c1 or 2ea44f.Default: blue.
Stylestyletext
Badge visual style. Defaults to flat when omitted.One of: flat, flat-square, plastic, for-the-badge, social.
Logologotext
Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker).
Logo colorlogo_colortext
Optional color for the logo (a named color or hex code).
Logo sizelogo_sizetext
Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos.One of: auto.
Label colorlabel_colortext
Optional background color for the label (left) side of the badge.
Cache secondscache_secondsnumber
HTTP cache lifetime for the badge, in seconds. Shields.io ignores a value below its own per-badge default (300 for most badges), so this can only make a badge refresh less often, never more.At least 0.

Outputs

badgeobject
Example output
{
  "badge": {
    "content_type": "image/svg+xml;charset=utf-8",
    "html": "<img src=\"https://img.shields.io/badge/build-passing-brightgreen\" alt=\"build\">",
    "is_error": false,
    "label": "build",
    "markdown": "![build](https://img.shields.io/badge/build-passing-brightgreen)",
    "message": "passing",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"120\" height=\"20\"><title>build: passing</title></svg>",
    "url": "https://img.shields.io/badge/build-passing-brightgreen"
  }
}

Generate dynamic badge

Create a badge whose message is pulled live from a remote JSON, XML, YAML, or TOML document. Shields.io fetches the URL and applies your query to extract the value to display. The extracted value is returned as 'message' so later steps can use it too.

Inputs

Data URLdata_urltextRequired
URL of the JSON/XML/YAML/TOML document to read the value from.
QueryquerytextRequired
Selector for the value: a JSONPath for JSON, YAML, and TOML (e.g. $.version) or an XPath for XML.
Data typedata_typetext
Format of the source document. Defaults to JSON.One of: json, xml, yaml, toml. Default: json.
Labellabeltext
Left-side text (the subject) for the badge.
Colorcolortext
Optional badge color: a named color or a hex code. Defaults to Shields.io's own coloring when omitted.
Prefixprefixtext
Optional text prepended to the extracted value.
Suffixsuffixtext
Optional text appended to the extracted value.
Stylestyletext
Badge visual style. Defaults to flat when omitted.One of: flat, flat-square, plastic, for-the-badge, social.
Logologotext
Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker).
Logo colorlogo_colortext
Optional color for the logo (a named color or hex code).
Logo sizelogo_sizetext
Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos.One of: auto.
Label colorlabel_colortext
Optional background color for the label (left) side of the badge.
Cache secondscache_secondsnumber
HTTP cache lifetime for the badge, in seconds. Shields.io ignores a value below its own per-badge default (300 for most badges), so this can only make a badge refresh less often, never more.At least 0.

Outputs

badgeobject
Example output
{
  "badge": {
    "content_type": "image/svg+xml;charset=utf-8",
    "html": "<img src=\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.example.com%2Fdata.json&query=%24.version&label=version&color=blue\" alt=\"version\">",
    "is_error": false,
    "label": "version",
    "markdown": "![version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.example.com%2Fdata.json&query=%24.version&label=version&color=blue)",
    "message": "1.4.2",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"120\" height=\"20\"><title>version: 1.4.2</title></svg>",
    "url": "https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.example.com%2Fdata.json&query=%24.version&label=version&color=blue"
  }
}

Generate endpoint badge

Create a badge from your own JSON endpoint. The endpoint decides the label, message, and color, so one URL can drive a badge whose text and color change over time. The endpoint must return {"schemaVersion": 1, "label": ..., "message": ..., "color": ...}.

Inputs

Endpoint URLendpoint_urltextRequired
HTTPS URL that returns Shields.io endpoint JSON: schemaVersion (always 1), label, message, and optionally color, labelColor, isError, namedLogo, logoSvg, logoColor, logoSize, and style.
Labellabeltext
Optional left-side text. Overrides the label the badge would otherwise show.
Colorcolortext
Optional badge color: a named color or a hex code. Defaults to Shields.io's own coloring when omitted.
Stylestyletext
Badge visual style. Defaults to flat when omitted.One of: flat, flat-square, plastic, for-the-badge, social.
Logologotext
Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker).
Logo colorlogo_colortext
Optional color for the logo (a named color or hex code).
Logo sizelogo_sizetext
Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos.One of: auto.
Label colorlabel_colortext
Optional background color for the label (left) side of the badge.
Cache secondscache_secondsnumber
HTTP cache lifetime for the badge, in seconds. Shields.io ignores a value below its own per-badge default (300 for most badges), so this can only make a badge refresh less often, never more.At least 0.

Outputs

badgeobject
Example output
{
  "badge": {
    "content_type": "image/svg+xml;charset=utf-8",
    "html": "<img src=\"https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.example.com%2Fbadge.json\" alt=\"badge\">",
    "is_error": false,
    "label": "deploy",
    "markdown": "![badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.example.com%2Fbadge.json)",
    "message": "healthy",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"120\" height=\"20\"><title>deploy: healthy</title></svg>",
    "url": "https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.example.com%2Fbadge.json"
  }
}

Generate license badge

Create a license badge, for example 'license | MIT'. The label is fixed to 'license'.

Inputs

LicenselicensetextRequired
The license identifier, for example 'MIT' or 'Apache-2.0'.
Colorcolortext
Badge color: a named color (brightgreen, green, yellow, orange, red, blue, lightgrey, etc.) or a hex code such as 4c1 or 2ea44f.Default: blue.
Stylestyletext
Badge visual style. Defaults to flat when omitted.One of: flat, flat-square, plastic, for-the-badge, social.
Logologotext
Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker).
Logo colorlogo_colortext
Optional color for the logo (a named color or hex code).
Logo sizelogo_sizetext
Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos.One of: auto.
Label colorlabel_colortext
Optional background color for the label (left) side of the badge.
Cache secondscache_secondsnumber
HTTP cache lifetime for the badge, in seconds. Shields.io ignores a value below its own per-badge default (300 for most badges), so this can only make a badge refresh less often, never more.At least 0.

Outputs

badgeobject
Example output
{
  "badge": {
    "content_type": "image/svg+xml;charset=utf-8",
    "html": "<img src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"license\">",
    "is_error": false,
    "label": "license",
    "markdown": "![license](https://img.shields.io/badge/license-MIT-blue)",
    "message": "MIT",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"120\" height=\"20\"><title>license: MIT</title></svg>",
    "url": "https://img.shields.io/badge/license-MIT-blue"
  }
}

Generate regex badge

Create a badge whose message is found by a regular expression in any remote text file: a README, a changelog, a config file. Shields.io fetches the URL, takes the first match, and shows it (or your rewritten version of it) as the badge message.

Inputs

Data URLdata_urltextRequired
URL of the text file to search.
SearchsearchtextRequired
An RE2 regular expression. Only the first match is used. Capture groups, named (?<name>...) or numbered, can be referenced from 'replace'.
Replacereplacetext
Optional rewrite of the match: $1 inserts the first capture group, $<name> a named group, $$ a literal dollar sign. Leave empty to show the whole match.
Flagsflagstext
Optional regex flags, any combination of i (case-insensitive), m (multi-line), and s (dot matches newlines), for example 'im'.
Labellabeltext
Optional left-side text. Overrides the label the badge would otherwise show.
Colorcolortext
Optional badge color: a named color or a hex code. Defaults to Shields.io's own coloring when omitted.
Stylestyletext
Badge visual style. Defaults to flat when omitted.One of: flat, flat-square, plastic, for-the-badge, social.
Logologotext
Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker).
Logo colorlogo_colortext
Optional color for the logo (a named color or hex code).
Logo sizelogo_sizetext
Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos.One of: auto.
Label colorlabel_colortext
Optional background color for the label (left) side of the badge.
Cache secondscache_secondsnumber
HTTP cache lifetime for the badge, in seconds. Shields.io ignores a value below its own per-badge default (300 for most badges), so this can only make a badge refresh less often, never more.At least 0.

Outputs

badgeobject
Example output
{
  "badge": {
    "content_type": "image/svg+xml;charset=utf-8",
    "html": "<img src=\"https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fexample.com%2FCHANGELOG.md&search=version+-+%28.%2A%29&replace=%241&label=version\" alt=\"version\">",
    "is_error": false,
    "label": "version",
    "markdown": "![version](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fexample.com%2FCHANGELOG.md&search=version+-+%28.%2A%29&replace=%241&label=version)",
    "message": "2.4",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"120\" height=\"20\"><title>version: 2.4</title></svg>",
    "url": "https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fexample.com%2FCHANGELOG.md&search=version+-+%28.%2A%29&replace=%241&label=version"
  }
}

Generate service badge

Create any of Shields.io's ready-made service badges by its path: GitHub stars, npm downloads, PyPI version, Docker pulls, CI status, and hundreds more. Shields.io pulls the live value from the service; the result's 'message' carries it too.

Inputs

Badge pathbadge_pathtextRequired
The badge's path on img.shields.io, as shown in the catalogue at https://shields.io/badges, for example github/stars/owner/repo or npm/v/package. A full https://img.shields.io/... URL pasted from the badge builder works too.
Labellabeltext
Optional left-side text. Overrides the label the badge would otherwise show.
Colorcolortext
Optional badge color: a named color or a hex code. Defaults to Shields.io's own coloring when omitted.
Stylestyletext
Badge visual style. Defaults to flat when omitted.One of: flat, flat-square, plastic, for-the-badge, social.
Logologotext
Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker).
Logo colorlogo_colortext
Optional color for the logo (a named color or hex code).
Logo sizelogo_sizetext
Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos.One of: auto.
Label colorlabel_colortext
Optional background color for the label (left) side of the badge.
Cache secondscache_secondsnumber
HTTP cache lifetime for the badge, in seconds. Shields.io ignores a value below its own per-badge default (300 for most badges), so this can only make a badge refresh less often, never more.At least 0.

Outputs

badgeobject
Example output
{
  "badge": {
    "content_type": "image/svg+xml;charset=utf-8",
    "html": "<img src=\"https://img.shields.io/github/stars/badges/shields\" alt=\"github\">",
    "is_error": false,
    "label": "stars",
    "markdown": "![github](https://img.shields.io/github/stars/badges/shields)",
    "message": "24k",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"120\" height=\"20\"><title>stars: 24k</title></svg>",
    "url": "https://img.shields.io/github/stars/badges/shields"
  }
}

Generate version badge

Create a version badge, for example 'Python | v3.8'. The version is prefixed with 'v' automatically unless you already included it.

Inputs

LabellabeltextRequired
Left-side text (the subject), for example 'Python'.
VersionversiontextRequired
The version string, for example '3.8' or 'v3.8'.
Colorcolortext
Badge color: a named color (brightgreen, green, yellow, orange, red, blue, lightgrey, etc.) or a hex code such as 4c1 or 2ea44f.Default: blue.
Stylestyletext
Badge visual style. Defaults to flat when omitted.One of: flat, flat-square, plastic, for-the-badge, social.
Logologotext
Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker).
Logo colorlogo_colortext
Optional color for the logo (a named color or hex code).
Logo sizelogo_sizetext
Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos.One of: auto.
Label colorlabel_colortext
Optional background color for the label (left) side of the badge.
Cache secondscache_secondsnumber
HTTP cache lifetime for the badge, in seconds. Shields.io ignores a value below its own per-badge default (300 for most badges), so this can only make a badge refresh less often, never more.At least 0.

Outputs

badgeobject
Example output
{
  "badge": {
    "content_type": "image/svg+xml;charset=utf-8",
    "html": "<img src=\"https://img.shields.io/badge/Python-v3.8-blue\" alt=\"Python\">",
    "is_error": false,
    "label": "Python",
    "markdown": "![Python](https://img.shields.io/badge/Python-v3.8-blue)",
    "message": "v3.8",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"120\" height=\"20\"><title>Python: v3.8</title></svg>",
    "url": "https://img.shields.io/badge/Python-v3.8-blue"
  }
}

SFTP

Previous Page

Shippo

Next Page

On this page

ActionsGenerate badgeGenerate dynamic badgeGenerate endpoint badgeGenerate license badgeGenerate regex badgeGenerate service badgeGenerate version badge