API Documentation

Overview

BarBuilder generates SVG progress bars via simple HTTP GET requests. Every parameter is passed as a URL path segment or query string — no API keys, no authentication, no POST bodies.

Responses are SVG images (image/svg+xml) that can be embedded anywhere: GitHub READMEs, documentation, dashboards, emails, or any HTML page.

Base URL

https://api.barbuilder.dev

All endpoints are served from the edge with global sub-50ms latency.

Endpoints

GET /percentage/{value}

Generates a progress bar for a percentage value.

Path Parameter Type Description
value number Percentage from 0 to 100 (decimals allowed)
Example
https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue&label=Progress
75% pill progress bar

GET /xofy/{current}/{total}

Generates a progress bar showing current out of total.

Path Parameter Type Description
current integer 0 to 999999
total integer 1 to 999999
Example
https://api.barbuilder.dev/xofy/7/10?style=segments&color=1e90ff&label=Tasks
7 of 10 segments

GET /icon/{current}/{total}

Generates an icon-based progress indicator (e.g. star ratings). Supports half-step rendering for fractional values.

Path Parameter Type Description
current number 0 to 50 (decimals allowed for half-steps)
total integer 1 to 50 (default: 5)
Example
https://api.barbuilder.dev/icon/3.5/5?shape=star&color=ffd700&label=Rating
3.5 out of 5 stars

Query Parameters

All parameters are optional. Unknown parameters are silently ignored.

Parameter Type Default Description
style string classic Bar style: classic, pill, minimal, badge, segments
color string 44cc11 Progress colour — hex (no #) or named colour
colorFrom string — Gradient start colour
colorTo string — Gradient end colour
colorSteps string — Threshold colours: 33:red,66:gold,100:green
backgroundColor string theme-based Unfilled area colour
theme string light light or dark
label string auto Text label (max 50 characters)
width integer 200 Width in pixels (50–500)
segments integer auto Segment count for segments style (2–20)
shape string star Icon shape: star, heart, circle, 8bit-heart

style

Controls the visual appearance of the progress bar.

classic
classic style

Traditional bar with label section

pill
pill style

Rounded ends, modern look

minimal
minimal style

Thin bar, no labels

badge
badge style

Badge style with auto-value

segments
segments style

Discrete blocks

color

Accepts a hex value (without #) or a named CSS colour. Both 3-digit and 6-digit hex are supported.

?color=ff6347 # 6-digit hex ?color=4c1 # 3-digit hex (expands to #44cc11) ?color=tomato # CSS named colour (case-insensitive)

Gradients (colorFrom & colorTo)

Set both colorFrom and colorTo to create a left-to-right gradient fill.

?colorFrom=667eea&colorTo=764ba2
gradient example

Threshold Colours (colorSteps)

Define colour breakpoints that change based on the progress value. Format: threshold:colour,threshold:colour,...

?colorSteps=33:crimson,66:gold,100:limegreen
threshold example

backgroundColor

Sets the colour of the unfilled area. Defaults depend on theme:

  • Light theme: #e0e0e0
  • Dark theme: #333333

theme

Controls default colours for backgrounds, borders, and labels.

Theme Background Label BG Label Text Progress Colour
light #e0e0e0 #555555 #ffffff #44cc11
dark #333333 #1a1a1a #e0e0e0 #55dd55

label

Custom text label. Maximum 50 characters (truncated with ... if exceeded). If omitted, a label is auto-generated based on the progress type.

width

Width in pixels, between 50 and 500. Default: 200.

segments

Number of discrete blocks when using the segments style. Range: 2–20. For X-of-Y progress, defaults to the total value (clamped to 2–20).

shape

Icon shape for the /icon endpoint. All shapes support half-step rendering for fractional values.

Shape Description
star Five-pointed star (default)
heart Classic heart shape
circle Filled circle
8bit-heart Retro pixel art heart with black outline

Named Colours

The following CSS colour names are supported (case-insensitive). You can also use any 3-digit or 6-digit hex value.

Reds

red crimson tomato coral indianred salmon darksalmon lightcoral lightsalmon

Oranges

orange orangered darkorange

Yellows

yellow gold khaki

Greens

green lime limegreen mediumseagreen springgreen seagreen forestgreen darkgreen olive lightgreen palegreen

Blues

blue navy royalblue steelblue dodgerblue deepskyblue cornflowerblue skyblue teal cyan turquoise

Purples & Pinks

purple indigo blueviolet mediumpurple rebeccapurple violet magenta deeppink hotpink pink

Browns

maroon brown saddlebrown chocolate peru tan

Greys

black dimgray gray silver lightgray whitesmoke white

Caching

Successful responses are aggressively cached at the edge for maximum performance. 

Cache-Control: public, max-age=31536000, immutable
Content-Type: image/svg+xml
Vary: Accept-Encoding
  • Cache hit (~95% of requests): <10ms response time
  • Cache miss (~5%): <50ms (generated at edge)
  • Same URL always produces the same SVG — URLs are effectively permanent
  • Error responses are never cached (Cache-Control: no-store)

Error Handling

Errors are returned as SVG images (not JSON) so they remain visible when embedded in READMEs or documentation. HTTP status 400 is used for all validation errors. 

HTTP/1.1 400 Bad Request
Content-Type: image/svg+xml
Cache-Control: no-store

Common error messages:

Cause Error Message
Percentage out of range Invalid percentage value '150' (must be 0-100)
Invalid style Unknown style 'foo' (valid: classic, pill, minimal, badge, segments)
Invalid colour Invalid color 'notacolor' (use hex or CSS named color)
Bad colorSteps format Invalid colorSteps format (use 'threshold:color,...')
Width out of range Invalid width '5000' (must be 50-500)
Segments out of range Invalid segments '100' (must be 2-20)

Lenient defaults

Minor issues are handled gracefully rather than returning errors:

  • Missing style → defaults to classic
  • Missing color → defaults to theme colour
  • Missing label → auto-generated based on type
  • Unknown query parameters → silently ignored
  • Labels exceeding 50 characters → truncated with ...

Examples

GitHub README Badge

![Build](https://api.barbuilder.dev/percentage/100?style=badge&color=4c1&label=Build)
Build badge

Star Rating

![Rating](https://api.barbuilder.dev/icon/4.5/5?shape=star&color=ffd700&label=Rating)
Star rating

Task Progress

![Tasks](https://api.barbuilder.dev/xofy/7/10?style=segments&color=1e90ff&label=Tasks)
Task progress

Dark Theme

![Progress](https://api.barbuilder.dev/percentage/65?style=minimal&color=4c71ff&theme=dark)
Dark theme

Gradient Fill

![Gradient](https://api.barbuilder.dev/percentage/80?style=pill&colorFrom=667eea&colorTo=764ba2)
Gradient fill

HTML Embedding

<img src="https://api.barbuilder.dev/percentage/75?style=pill&color=dodgerblue"
     alt="75% progress"
     height="20">