# Shields.io > 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. App · Utilities · 7 actions. Web page: https://docs.lodol.com/docs/integrations/shields-io ## Actions ### 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** - Label (`label`, text, required): Left-side text (the subject), for example 'build' or 'coverage'. - Message (`message`, text, required): Right-side text (the status), for example 'passing' or '98%'. - Color (`color`, text): Badge color: a named color (brightgreen, green, yellow, orange, red, blue, lightgrey, etc.) or a hex code such as 4c1 or 2ea44f. Default: `blue`. - Style (`style`, text): Badge visual style. Defaults to flat when omitted. One of: `flat`, `flat-square`, `plastic`, `for-the-badge`, `social`. - Logo (`logo`, text): Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker). - Logo color (`logo_color`, text): Optional color for the logo (a named color or hex code). - Logo size (`logo_size`, text): Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos. One of: `auto`. - Label color (`label_color`, text): Optional background color for the label (left) side of the badge. - Cache seconds (`cache_seconds`, number): 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** - `badge` (object) **Example output** ```json { "badge": { "content_type": "image/svg+xml;charset=utf-8", "html": "\"build\"", "is_error": false, "label": "build", "markdown": "![build](https://img.shields.io/badge/build-passing-brightgreen)", "message": "passing", "svg": "build: passing", "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 URL (`data_url`, text, required): URL of the JSON/XML/YAML/TOML document to read the value from. - Query (`query`, text, required): Selector for the value: a JSONPath for JSON, YAML, and TOML (e.g. $.version) or an XPath for XML. - Data type (`data_type`, text): Format of the source document. Defaults to JSON. One of: `json`, `xml`, `yaml`, `toml`. Default: `json`. - Label (`label`, text): Left-side text (the subject) for the badge. - Color (`color`, text): Optional badge color: a named color or a hex code. Defaults to Shields.io's own coloring when omitted. - Prefix (`prefix`, text): Optional text prepended to the extracted value. - Suffix (`suffix`, text): Optional text appended to the extracted value. - Style (`style`, text): Badge visual style. Defaults to flat when omitted. One of: `flat`, `flat-square`, `plastic`, `for-the-badge`, `social`. - Logo (`logo`, text): Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker). - Logo color (`logo_color`, text): Optional color for the logo (a named color or hex code). - Logo size (`logo_size`, text): Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos. One of: `auto`. - Label color (`label_color`, text): Optional background color for the label (left) side of the badge. - Cache seconds (`cache_seconds`, number): 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** - `badge` (object) **Example output** ```json { "badge": { "content_type": "image/svg+xml;charset=utf-8", "html": "\"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": "version: 1.4.2", "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 URL (`endpoint_url`, text, required): HTTPS URL that returns Shields.io endpoint JSON: schemaVersion (always 1), label, message, and optionally color, labelColor, isError, namedLogo, logoSvg, logoColor, logoSize, and style. - Label (`label`, text): Optional left-side text. Overrides the label the badge would otherwise show. - Color (`color`, text): Optional badge color: a named color or a hex code. Defaults to Shields.io's own coloring when omitted. - Style (`style`, text): Badge visual style. Defaults to flat when omitted. One of: `flat`, `flat-square`, `plastic`, `for-the-badge`, `social`. - Logo (`logo`, text): Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker). - Logo color (`logo_color`, text): Optional color for the logo (a named color or hex code). - Logo size (`logo_size`, text): Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos. One of: `auto`. - Label color (`label_color`, text): Optional background color for the label (left) side of the badge. - Cache seconds (`cache_seconds`, number): 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** - `badge` (object) **Example output** ```json { "badge": { "content_type": "image/svg+xml;charset=utf-8", "html": "\"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": "deploy: healthy", "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** - License (`license`, text, required): The license identifier, for example 'MIT' or 'Apache-2.0'. - Color (`color`, text): Badge color: a named color (brightgreen, green, yellow, orange, red, blue, lightgrey, etc.) or a hex code such as 4c1 or 2ea44f. Default: `blue`. - Style (`style`, text): Badge visual style. Defaults to flat when omitted. One of: `flat`, `flat-square`, `plastic`, `for-the-badge`, `social`. - Logo (`logo`, text): Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker). - Logo color (`logo_color`, text): Optional color for the logo (a named color or hex code). - Logo size (`logo_size`, text): Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos. One of: `auto`. - Label color (`label_color`, text): Optional background color for the label (left) side of the badge. - Cache seconds (`cache_seconds`, number): 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** - `badge` (object) **Example output** ```json { "badge": { "content_type": "image/svg+xml;charset=utf-8", "html": "\"license\"", "is_error": false, "label": "license", "markdown": "![license](https://img.shields.io/badge/license-MIT-blue)", "message": "MIT", "svg": "license: MIT", "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 URL (`data_url`, text, required): URL of the text file to search. - Search (`search`, text, required): An RE2 regular expression. Only the first match is used. Capture groups, named (?...) or numbered, can be referenced from 'replace'. - Replace (`replace`, text): Optional rewrite of the match: $1 inserts the first capture group, $ a named group, $$ a literal dollar sign. Leave empty to show the whole match. - Flags (`flags`, text): Optional regex flags, any combination of i (case-insensitive), m (multi-line), and s (dot matches newlines), for example 'im'. - Label (`label`, text): Optional left-side text. Overrides the label the badge would otherwise show. - Color (`color`, text): Optional badge color: a named color or a hex code. Defaults to Shields.io's own coloring when omitted. - Style (`style`, text): Badge visual style. Defaults to flat when omitted. One of: `flat`, `flat-square`, `plastic`, `for-the-badge`, `social`. - Logo (`logo`, text): Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker). - Logo color (`logo_color`, text): Optional color for the logo (a named color or hex code). - Logo size (`logo_size`, text): Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos. One of: `auto`. - Label color (`label_color`, text): Optional background color for the label (left) side of the badge. - Cache seconds (`cache_seconds`, number): 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** - `badge` (object) **Example output** ```json { "badge": { "content_type": "image/svg+xml;charset=utf-8", "html": "\"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": "version: 2.4", "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 path (`badge_path`, text, required): 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. - Label (`label`, text): Optional left-side text. Overrides the label the badge would otherwise show. - Color (`color`, text): Optional badge color: a named color or a hex code. Defaults to Shields.io's own coloring when omitted. - Style (`style`, text): Badge visual style. Defaults to flat when omitted. One of: `flat`, `flat-square`, `plastic`, `for-the-badge`, `social`. - Logo (`logo`, text): Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker). - Logo color (`logo_color`, text): Optional color for the logo (a named color or hex code). - Logo size (`logo_size`, text): Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos. One of: `auto`. - Label color (`label_color`, text): Optional background color for the label (left) side of the badge. - Cache seconds (`cache_seconds`, number): 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** - `badge` (object) **Example output** ```json { "badge": { "content_type": "image/svg+xml;charset=utf-8", "html": "\"github\"", "is_error": false, "label": "stars", "markdown": "![github](https://img.shields.io/github/stars/badges/shields)", "message": "24k", "svg": "stars: 24k", "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** - Label (`label`, text, required): Left-side text (the subject), for example 'Python'. - Version (`version`, text, required): The version string, for example '3.8' or 'v3.8'. - Color (`color`, text): Badge color: a named color (brightgreen, green, yellow, orange, red, blue, lightgrey, etc.) or a hex code such as 4c1 or 2ea44f. Default: `blue`. - Style (`style`, text): Badge visual style. Defaults to flat when omitted. One of: `flat`, `flat-square`, `plastic`, `for-the-badge`, `social`. - Logo (`logo`, text): Optional named logo to show before the label (a Simple Icons slug, e.g. github, python, docker). - Logo color (`logo_color`, text): Optional color for the logo (a named color or hex code). - Logo size (`logo_size`, text): Set to 'auto' to shrink a wide logo to fit the badge height. Only applies to Simple Icons logos. One of: `auto`. - Label color (`label_color`, text): Optional background color for the label (left) side of the badge. - Cache seconds (`cache_seconds`, number): 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** - `badge` (object) **Example output** ```json { "badge": { "content_type": "image/svg+xml;charset=utf-8", "html": "\"Python\"", "is_error": false, "label": "Python", "markdown": "![Python](https://img.shields.io/badge/Python-v3.8-blue)", "message": "v3.8", "svg": "Python: v3.8", "url": "https://img.shields.io/badge/Python-v3.8-blue" } } ```