{"openapi":"3.1.0","info":{"title":"Cron Translator","version":"1.0.0","summary":"Translate cron expressions to plain English — and back.","description":"Explain any cron expression in plain English, see the next run times in any timezone, and catch the gotchas that make schedules misfire: day-of-month/day-of-week OR semantics, steps that do not divide evenly, impossible dates, and daylight-saving shifts.\n\n**Not for:** Does not run, install, or manage scheduled jobs. Does not support Quartz extensions (L, W, #, ?) beyond detecting and reporting them.\n\nFree tier: 250 calls per UTC day per caller. Past that, endpoints return 402 with x402 payment requirements. An MCP server exposing the same capabilities is available at https://crontoenglish.com/api/mcp.","contact":{"url":"https://github.com/bwalvoord/gumball"}},"servers":[{"url":"https://crontoenglish.com","description":"Production"}],"externalDocs":{"url":"https://crontoenglish.com/llms-full.txt","description":"Full documentation for agents"},"paths":{"/api/v1/explain":{"get":{"operationId":"explainCron","summary":"Explain a cron expression in plain English","description":"Returns an English description, a per-field breakdown, warnings about common cron traps (day-of-month/day-of-week OR semantics, uneven steps, impossible dates, DST), and the next run times.","parameters":[{"name":"expression","in":"query","required":true,"description":"Standard five-field cron expression: \"minute hour day-of-month month day-of-week\". Accepts *, numbers, ranges, lists, steps, three-letter month/day names, and the @daily/@hourly/@weekly/@monthly/@yearly macros.","schema":{"type":"string","examples":["0 9 * * 1-5","*/15 9-17 * * 1-5","@daily"]}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone name. Cron expressions carry no timezone, so this decides when the schedule fires.","schema":{"type":"string","default":"UTC","examples":["UTC","America/New_York"]}},{"name":"count","in":"query","required":false,"description":"How many upcoming run times to return.","schema":{"type":"integer","minimum":1,"maximum":25,"default":5}}],"responses":{"200":{"description":"The expression, explained.","content":{"application/json":{"schema":{"type":"object","required":["input","expression","description","fields","warnings","timezone","nextRuns"],"properties":{"input":{"type":"string"},"expression":{"type":"string","description":"Normalised five-field expression."},"description":{"type":"string","description":"One-sentence plain English description."},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["minute","hour","dayOfMonth","month","dayOfWeek"]},"label":{"type":"string"},"raw":{"type":"string"},"description":{"type":"string"},"values":{"type":"array","items":{"type":"integer"}}}}},"warnings":{"type":"array","items":{"type":"object","required":["code","severity","title","detail"],"properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["info","caution","error"]},"title":{"type":"string"},"detail":{"type":"string"},"fixHint":{"type":"string"}}}},"timezone":{"type":"string"},"nextRuns":{"type":"array","items":{"type":"object","required":["iso","local"],"properties":{"iso":{"type":"string","format":"date-time","description":"UTC instant, ISO 8601."},"local":{"type":"string","description":"Wall-clock rendering in the requested timezone."}}}},"runsPerDayEstimate":{"type":"integer"},"macro":{"type":["string","null"]}}}}}},"400":{"description":"Invalid input. The body names the field and how to fix it.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fix_hint","docs"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"},"fix_hint":{"type":"string","description":"What to change before retrying."},"field":{"type":"string"},"token":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"docs":{"type":"string","format":"uri"}}}}}}}},"402":{"description":"Free quota of 250 calls per UTC day exhausted. Body is an x402 v1 payment requirement ($0.001 per call, USDC on Base). While settlement is disabled the body carries payment_enabled: false and the call cannot be unblocked by paying — wait for quota.resetsAt.","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"payment_enabled":{"type":"boolean"},"accepts":{"type":"array","items":{"type":"object"}},"quota":{"type":"object"},"fix_hint":{"type":"string"},"docs":{"type":"string"}}}}}}}}},"/api/v1/next-runs":{"get":{"operationId":"nextCronRuns","summary":"List the next run times for a cron expression","description":"Upcoming run times only. Each run is given as a UTC ISO 8601 instant and a local wall-clock string. Refuses Quartz-only syntax rather than guessing.","parameters":[{"name":"expression","in":"query","required":true,"description":"Standard five-field cron expression: \"minute hour day-of-month month day-of-week\". Accepts *, numbers, ranges, lists, steps, three-letter month/day names, and the @daily/@hourly/@weekly/@monthly/@yearly macros.","schema":{"type":"string","examples":["0 9 * * 1-5","*/15 9-17 * * 1-5","@daily"]}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone name. Cron expressions carry no timezone, so this decides when the schedule fires.","schema":{"type":"string","default":"UTC","examples":["UTC","America/New_York"]}},{"name":"count","in":"query","required":false,"description":"How many upcoming run times to return.","schema":{"type":"integer","minimum":1,"maximum":25,"default":5}}],"responses":{"200":{"description":"Upcoming run times.","content":{"application/json":{"schema":{"type":"object","properties":{"expression":{"type":"string"},"timezone":{"type":"string"},"count":{"type":"integer"},"runs":{"type":"array","items":{"type":"object","required":["iso","local"],"properties":{"iso":{"type":"string","format":"date-time","description":"UTC instant, ISO 8601."},"local":{"type":"string","description":"Wall-clock rendering in the requested timezone."}}}}}}}}},"400":{"description":"Invalid input. The body names the field and how to fix it.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fix_hint","docs"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"},"fix_hint":{"type":"string","description":"What to change before retrying."},"field":{"type":"string"},"token":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"docs":{"type":"string","format":"uri"}}}}}}}},"402":{"description":"Free quota of 250 calls per UTC day exhausted. Body is an x402 v1 payment requirement ($0.001 per call, USDC on Base). While settlement is disabled the body carries payment_enabled: false and the call cannot be unblocked by paying — wait for quota.resetsAt.","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"payment_enabled":{"type":"boolean"},"accepts":{"type":"array","items":{"type":"object"}},"quota":{"type":"object"},"fix_hint":{"type":"string"},"docs":{"type":"string"}}}}}}}}},"/api/v1/build":{"get":{"operationId":"buildCron","summary":"Build a cron expression from an English phrase","description":"Rule-based English-to-cron conversion — not a language model. Returns 400 with the list of supported phrasings when a phrase falls outside the grammar, rather than guessing. Inspect `ignored_words`: leftover words can mean the phrase was misread.","parameters":[{"name":"phrase","in":"query","required":true,"description":"English schedule description.","schema":{"type":"string","examples":["every minute","every 5 minutes","every hour","every 6 hours","every day at 9am","every day at 14:30","every monday at 9am","every weekday at 8:15am","every weekend at 10am","on the 1st of every month at midnight","every year on January 1 at noon"]}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone name. Cron expressions carry no timezone, so this decides when the schedule fires.","schema":{"type":"string","default":"UTC","examples":["UTC","America/New_York"]}}],"responses":{"200":{"description":"The expression, plus its explanation.","content":{"application/json":{"schema":{"type":"object","properties":{"phrase":{"type":"string"},"expression":{"type":"string"},"matched_rule":{"type":"string"},"ignored_words":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"warnings":{"type":"array","items":{"type":"object","required":["code","severity","title","detail"],"properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["info","caution","error"]},"title":{"type":"string"},"detail":{"type":"string"},"fixHint":{"type":"string"}}}},"next_runs":{"type":"array","items":{"type":"object","required":["iso","local"],"properties":{"iso":{"type":"string","format":"date-time","description":"UTC instant, ISO 8601."},"local":{"type":"string","description":"Wall-clock rendering in the requested timezone."}}}},"timezone":{"type":"string"}}}}}},"400":{"description":"Invalid input. The body names the field and how to fix it.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fix_hint","docs"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"},"fix_hint":{"type":"string","description":"What to change before retrying."},"field":{"type":"string"},"token":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"docs":{"type":"string","format":"uri"}}}}}}}},"402":{"description":"Free quota of 250 calls per UTC day exhausted. Body is an x402 v1 payment requirement ($0.001 per call, USDC on Base). While settlement is disabled the body carries payment_enabled: false and the call cannot be unblocked by paying — wait for quota.resetsAt.","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"payment_enabled":{"type":"boolean"},"accepts":{"type":"array","items":{"type":"object"}},"quota":{"type":"object"},"fix_hint":{"type":"string"},"docs":{"type":"string"}}}}}}}}}}}