v1API reference

Documentation

API Reference

cronbadge.dev converts Unix 5-field cron expressions into JSON, GitHub-style badges, and larger SVG schedule cards.

GET/api/v1/parseParse

JSON with `dialect`, `expression`, `timezone`, `summary`, `nextRun`, `nextRuns`, and `warnings`.

Parameters

exprrequiredUnix 5-field cron expression
tzoptionalIANA timezone, defaults to `UTC`
countoptionalNumber of upcoming runs to return

Request

/api/v1/parse?expr=%2A%2F5%20%2A%20%2A%20%2A%20%2A&tz=UTC&count=3
GET/api/v1/badge.svgBadge

SVG badge using the GitHub-style split label/value layout.

Parameters

exprrequiredUnix 5-field cron expression
tzoptionalIANA timezone, defaults to `UTC`
labeloptionalLeft-side badge text, defaults to `cron`
summaryoptionalSet to `hide` to remove summary text from the right segment
nextoptionalSet to `hide` to remove next-run text
prevoptionalSet to `show` to include previous-run text
timeFormatoptional`time`, `weekday-time`, `date-time`, or `iso`
themeoptional`light` or `dark`

Request

/api/v1/badge.svg?expr=0%2012%20%2A%20%2A%201&tz=Europe%2FAmsterdam&label=production&summary=hide&next=show&timeFormat=weekday-time
GET/api/v1/card.svgCard

Larger SVG schedule card using the same split-badge visual language.

Parameters

exprrequiredUnix 5-field cron expression
tzoptionalIANA timezone, defaults to `UTC`
countoptionalNumber of next runs to include
themeoptional`light` or `dark`
timezoneLabeloptionalSet to `hide` to hide timezone chip
expressionoptionalSet to `hide` to hide raw cron chip
nextRunLabeloptionalSet to `hide` to hide next-run chip

Request

/api/v1/card.svg?expr=30%209%20%2A%20%2A%201-5&tz=Europe%2FAmsterdam&theme=light&count=3&timezoneLabel=show&expression=show&nextRunLabel=show

Operational Bounds

  • Cron syntax is Unix 5-field only: minute, hour, day of month, month, day of week.
  • Unsupported syntax includes macros like `@daily` and Quartz-specific tokens such as `?`, `L`, `W`, and `#`.
  • The parse endpoint supports `count` values from 1 through 10 for upcoming runs.
  • Badge output is width-capped and truncates long visible text to keep the SVG embeddable in README contexts.
  • Card output is optimized for concise schedule previews and currently renders up to 8 visible upcoming runs cleanly.
  • Timezone input can be any IANA timezone recognized by the deployed runtime. See `/api/v1/timezones` for the exact runtime-supported set.