Embed Real-Time Status Badges Anywhere
Status badges let you show your service health anywhere you can embed an image — GitHub READMEs, GitLab projects, documentation sites, internal dashboards. They update automatically and give users an at-a-glance view of your system status.
The Badge Endpoint
Upwarden provides a public endpoint for each monitor:
GET https://upwarden.eu/api/v1/badge/:monitorId.svg
No authentication required. Just replace :monitorId with your monitor's ID (found on the monitor detail page in your dashboard).
Basic Usage
Markdown (GitHub, GitLab, etc.):
HTML:
<img src="https://upwarden.eu/api/v1/badge/your-monitor-id.svg" alt="Status" />
With a link to your status page:
[](https://upwarden.eu/status/your-page-slug)
Customization Options
Badge Style
Add ?style=flat-square for sharp corners (default is flat with rounded corners):
Custom Label
Change the left side text with ?label=custom-text:
Combine both:
Status Colors
The badge color reflects your monitor's current status:
| Status | Color | Hex |
|---|---|---|
| Up | Green | #16a34a |
| Down | Red | #dc2626 |
| Degraded | Amber | #d97706 |
| Unknown | Gray | #71717a |
If the monitor doesn't exist, the badge returns "unknown" status with a gray color.
Caching
Badges are cached for 60 seconds (Cache-Control: public, max-age=60). This means:
- Badges update at most once per minute
- CDNs and browsers serve cached versions within that window
- An
ETagheader allows conditional requests
For monitors that don't exist, the response uses no-cache headers so you'll see the "unknown" state immediately.
Response Format
The endpoint returns image/svg+xml content. The SVG is shields.io-compatible with proper aria-label and title attributes for accessibility.
When to Use Badges
- README files — Show your service is operational right in your GitHub/GitLab repo
- Documentation sites — Let developers know if your API is healthy before they start integrating
- Internal dashboards — Aggregate status across multiple services on a single page
- Marketing pages — Demonstrate transparency and reliability to potential customers
Badges are a small but effective way to build trust. They show you take uptime seriously enough to display it publicly.