How to Create a Dynamic shields.io Endpoint Badge

The shields.io endpoint route renders a badge from a JSON document you host that declares schemaVersion, label, message, and color.

Publish a JSON file matching the shields endpoint schema, then reference it via img.shields.io/endpoint?url=<your-json>. shields fetches your JSON and renders the badge from its fields.

Steps

• Generate a JSON file with schemaVersion: 1, label, message, and color.
• Host it at a stable public URL (raw file, Pages, or an API).
• Reference it with the endpoint route in your README.

The JSON shields fetches

{
  "schemaVersion": 1,
  "label": "tests",
  "message": "428 passing",
  "color": "brightgreen"
}

README markdown

![Tests](https://img.shields.io/endpoint?url=https://acme.github.io/widget/badge.json)

Gotchas

• The endpoint URL must be publicly reachable over HTTPS; private URLs return an error badge.
• Keep message short; shields renders the raw string with no formatting.

Related guides