{"openapi":"3.0.3","info":{"title":"Cron & Schedule Explainer & Validator API","version":"1.0.0","description":"Validates 5-field, 6-field, and macro cron expressions (including L, W, #), translates them to plain English, and computes upcoming runs with IANA timezone & DST awareness."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"CronExplainResponseData":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"normalized_expression":{"type":"string","nullable":true,"example":"0 9 * * 1-5"},"format":{"type":"string","enum":["5-field","6-field","macro","reboot","invalid"],"example":"5-field"},"timezone":{"type":"string","example":"Europe/Budapest"},"explanation":{"type":"string","nullable":true,"example":"At 09:00, Monday through Friday (Europe/Budapest)"},"fields":{"type":"object","nullable":true,"properties":{"seconds":{"type":"string"},"minutes":{"type":"string"},"hours":{"type":"string"},"day_of_month":{"type":"string"},"month":{"type":"string"},"day_of_week":{"type":"string"}},"required":["seconds","minutes","hours","day_of_month","month","day_of_week"]},"next_runs":{"type":"array","items":{"type":"object","properties":{"iso_utc":{"type":"string","example":"2026-11-16T08:00:00.000Z"},"local_time":{"type":"string","example":"2026-11-16T09:00:00+01:00"},"epoch_ms":{"type":"integer","example":1794816000000},"utc_offset":{"type":"string","example":"+01:00"}},"required":["iso_utc","local_time","epoch_ms","utc_offset"]}},"warnings":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"string"}}},"required":["valid","normalized_expression","format","timezone","explanation","fields","next_runs","warnings","errors"]},"CronExplainRequest":{"type":"object","properties":{"expression":{"type":"string","minLength":1,"maxLength":256,"example":"0 9 * * 1-5","description":"5-field UNIX cron, 6-field cron (with leading seconds), or macro (@hourly, @daily, @weekly, @monthly, @yearly, @reboot). Supports L, W, and #."},"timezone":{"type":"string","minLength":1,"maxLength":64,"default":"UTC","example":"Europe/Budapest","description":"IANA timezone name (e.g. 'UTC', 'Europe/Budapest', 'America/New_York')."},"count":{"type":"integer","minimum":1,"maximum":50,"default":5,"example":5,"description":"Number of upcoming execution times to compute (1 to 50)."},"from_time":{"type":"string","example":"2026-11-14T08:00:00Z","description":"Optional ISO-8601 starting timestamp (defaults to current UTC time)."}},"required":["expression"]},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/cron-explainer":{"post":{"tags":["18_CRON_EXPLAINER"],"summary":"Validate a cron expression, explain it in plain English, and compute next N runs","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CronExplainRequest"}}}},"responses":{"200":{"description":"Validation status, plain-English explanation, and next N timezone-aware runs","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CronExplainResponseData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}