Radar Badge

Display your project's technical debt status directly in your README with a dynamic SVG badge. Badges update automatically after every analysis and give immediate visibility into your codebase health.

Badge URL Format

https://api.radardebt.dev/badge/{project-id}/{metric}.svg?style={style}

Parameter	Required	Description
project-id	Yes	Your project ID (found in Settings > Project)
metric	Yes	One of: debt-score, violations, gate-status, trend
style	No	One of: flat, flat-square, for-the-badge. Defaults to flat.

Available Metrics

debt-score

Shows the current debt delta score as a numeric value. Color ranges from green (low debt) through yellow (moderate) to red (high).

• Score 0--5: Green background, indicating a healthy codebase
• Score 6--14: Yellow background, indicating moderate debt
• Score 15+: Red background, indicating policy violations

Appearance: A two-tone badge. The left segment reads "radar debt" in white text on a dark gray background. The right segment shows the numeric score (e.g., "4") on a colored background that reflects severity.

violations

Shows the total number of active violations. Color follows the same green/yellow/red pattern.

• 0 violations: Green with the text "0"
• 1--4 violations: Yellow with the count
• 5+ violations: Red with the count

Appearance: Left segment reads "radar violations" on dark gray. Right segment shows the count on a severity-colored background.

gate-status

Shows the current merge gate status: PASS or FAIL.

• PASS: Green background with white "PASS" text
• FAIL: Red background with white "FAIL" text

Appearance: Left segment reads "radar gate" on dark gray. Right segment shows "PASS" (green) or "FAIL" (red).

trend

Shows the debt trend direction over the last 7 analyses.

• Improving (score decreasing): Green background with a downward arrow and "improving"
• Stable (score unchanged): Blue background with a horizontal arrow and "stable"
• Worsening (score increasing): Red background with an upward arrow and "worsening"

Appearance: Left segment reads "radar trend" on dark gray. Right segment shows the trend label with a directional arrow on a colored background.

Badge Styles

flat (default)

Rounded corners, subtle gradient, standard shields.io-compatible appearance. The most common badge style used in open-source projects.

flat-square

Sharp corners, flat color fill, no gradient. Matches the flat-square style common in minimalist READMEs.

for-the-badge

Larger badge with uppercase text, wider padding, and bolder appearance. Designed for prominent placement at the top of a README.

Embedding

Markdown

[![Radar Debt Score](https://api.radardebt.dev/badge/proj_abc123/debt-score.svg)](https://app.radardebt.dev/projects/proj_abc123)

[![Radar Gate](https://api.radardebt.dev/badge/proj_abc123/gate-status.svg?style=flat-square)](https://app.radardebt.dev/projects/proj_abc123)

[![Radar Trend](https://api.radardebt.dev/badge/proj_abc123/trend.svg?style=for-the-badge)](https://app.radardebt.dev/projects/proj_abc123)

HTML

<a href="https://app.radardebt.dev/projects/proj_abc123">
  <img
    src="https://api.radardebt.dev/badge/proj_abc123/debt-score.svg"
    alt="Radar Debt Score"
  />
</a>

reStructuredText

.. image:: https://api.radardebt.dev/badge/proj_abc123/debt-score.svg
   :target: https://app.radardebt.dev/projects/proj_abc123
   :alt: Radar Debt Score

Multiple Badges

Combine badges for a complete status overview in your README:

[![Debt Score](https://api.radardebt.dev/badge/proj_abc123/debt-score.svg)](https://app.radardebt.dev/projects/proj_abc123)
[![Gate Status](https://api.radardebt.dev/badge/proj_abc123/gate-status.svg)](https://app.radardebt.dev/projects/proj_abc123)
[![Violations](https://api.radardebt.dev/badge/proj_abc123/violations.svg)](https://app.radardebt.dev/projects/proj_abc123)
[![Trend](https://api.radardebt.dev/badge/proj_abc123/trend.svg)](https://app.radardebt.dev/projects/proj_abc123)

This renders as a row of four badges at the top of your README, each linking to your project dashboard.

Caching Behavior

Badge responses include caching headers to balance freshness with performance:

Header	Value	Effect
Cache-Control	max-age=300	Browsers and CDNs cache for 5 minutes
ETag	Content-based hash	Conditional requests return 304 Not Modified when unchanged

After a new analysis completes, the badge updates within 5 minutes. For immediate updates (e.g., in CI pipelines), append a cache-busting query parameter:

![Score](https://api.radardebt.dev/badge/proj_abc123/debt-score.svg?v=2)

Tip: GitHub caches badge images aggressively via its camo proxy. If your badge appears stale on GitHub, wait 10--15 minutes or use the ?v=timestamp trick to force a refresh.

Security

XSS Protection

All dynamic values rendered in the SVG are sanitized:

• Numeric scores are validated as integers before rendering
• Status strings are restricted to a whitelist (PASS, FAIL, improving, stable, worsening)
• No user-supplied strings are rendered in the SVG without escaping
• The SVG Content-Type header is set to image/svg+xml to prevent script execution

Authentication

Badge endpoints are public by default so they can be embedded in public READMEs. If your project is private, you can require a badge token:

1. Go to Settings > Badges in the Radar dashboard
2. Enable Require badge token
3. Copy the generated token
4. Append ?token=bdg_xxx to the badge URL

![Score](https://api.radardebt.dev/badge/proj_abc123/debt-score.svg?token=bdg_abc123xyz)

Tip: Badge tokens are read-only and cannot access any data beyond the badge SVG. They are safe to embed in public repositories even for private projects.