{"id":"recurrence-expand","title":"Expand an RRULE or 5-field cron into concrete occurrences with DST handling, exclusions and conflict detection","description":"Expands an RFC 5545 RRULE (FREQ DAILY/WEEKLY/MONTHLY/YEARLY, INTERVAL, COUNT, UNTIL, BYDAY with ordinals, BYMONTHDAY, BYMONTH, BYSETPOS, WKST; DTSTART with TZID; EXDATE) or a crontab(5) expression into up to 366 occurrences in a time zone, with the UTC instant of each, DST gap or overlap flags, caller blackout dates, a plain-English reading, and optionally the occurrences where it collides with a second rule. COUNT is applied before EXDATE removal, invalid dates (Feb 30) are skipped, a time in a gap is read with the pre-gap offset and an overlap uses its first occurrence (RFC 5545 3.3.5). Hourly/minutely FREQ, BYHOUR, BYYEARDAY, BYWEEKNO, RDATE, EXRULE, Quartz cron extensions and @macros return `unsupported`. Never reads the clock: the window starts at `from` (or DTSTART).","roi":"Whether a standup, report or billing job fires on the 5th Monday, on a gap day or twice on a fall-back night is decided here instead of guessed.","audience":"business","package":"calendar-deadline-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/recurrence-expand","path":"/api/v1/recurrence-expand","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["kind","rule"],"properties":{"kind":{"type":"string","enum":["rrule","cron"]},"rule":{"type":"string","maxLength":800,"description":"rrule: 'DTSTART;TZID=America/New_York:19970902T090000\\nRRULE:FREQ=DAILY;COUNT=10\\nEXDATE;TZID=America/New_York:19970903T090000' or just 'FREQ=...' with dtstart. cron: '*/15 9-17 * * 1-5' (dom and dow both restricted match if either does)."},"dtstart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$","maxLength":30,"description":"Local DTSTART when the rule text has none."},"timeZone":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+){0,2}$","maxLength":64,"description":"IANA zone for local times (required for cron; for rrule unless DTSTART has TZID or Z)."},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$","maxLength":30,"description":"Local start of the output window; required for cron, default DTSTART for rrule."},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$","maxLength":30,"description":"Local end of the window, inclusive."},"limit":{"type":"integer","minimum":1,"maximum":366,"description":"Maximum occurrences returned (default 20)."},"exdates":{"type":"array","maxItems":200,"items":{"type":"string","maxLength":30},"description":"Extra excluded local date-times (YYYY-MM-DDTHH:MM[:SS]) or dates (YYYY-MM-DD, excludes that day)."},"blackouts":{"type":"array","maxItems":50,"items":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","maxLength":10},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","maxLength":10}}},"description":"Inclusive local date ranges to drop (holidays, freezes)."},"durationMinutes":{"type":"integer","minimum":0,"maximum":43200,"description":"Occurrence length, for conflict overlap."},"other":{"type":"object","required":["kind","rule"],"description":"A second rule to compare; conflicts are occurrences whose intervals overlap (equal instants when both durations are 0).","properties":{"kind":{"type":"string","enum":["rrule","cron"]},"rule":{"type":"string","maxLength":800},"dtstart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$","maxLength":30},"timeZone":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+){0,2}$","maxLength":64},"durationMinutes":{"type":"integer","minimum":0,"maximum":43200}}}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"occurrences":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"local":{"type":"string"},"utc":{"type":"string"},"dst":{"type":"string","enum":["gap","overlap"]}}}},"count":{"type":"integer"},"description":{"type":"string"},"timeZone":{"type":"string"},"excluded":{"type":"array","items":{"type":"object","properties":{"local":{"type":"string"},"reason":{"type":"string"}}}},"moreAvailable":{"type":"boolean"},"scanCapped":{"type":"boolean"},"conflicts":{"type":"array","items":{"type":"object","properties":{"aIndex":{"type":"integer"},"bIndex":{"type":"integer"},"aUtc":{"type":"string"},"bUtc":{"type":"string"}}}},"comparedThroughUtc":{"type":"string"},"reason":{"type":"string"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"occurrences":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"local":{"type":"string"},"utc":{"type":"string"},"dst":{"type":"string","enum":["gap","overlap"]}}}},"count":{"type":"integer"},"description":{"type":"string"},"timeZone":{"type":"string"},"excluded":{"type":"array","items":{"type":"object","properties":{"local":{"type":"string"},"reason":{"type":"string"}}}},"moreAvailable":{"type":"boolean"},"scanCapped":{"type":"boolean"},"conflicts":{"type":"array","items":{"type":"object","properties":{"aIndex":{"type":"integer"},"bIndex":{"type":"integer"},"aUtc":{"type":"string"},"bUtc":{"type":"string"}}}},"comparedThroughUtc":{"type":"string"},"reason":{"type":"string"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"kind":"rrule","rule":"DTSTART;TZID=America/New_York:19970902T090000\nRRULE:FREQ=DAILY;COUNT=10","limit":10},"openapiOperation":{"operationId":"recurrence_expand","summary":"Expand an RRULE or 5-field cron into concrete occurrences with DST handling, exclusions and conflict detection","description":"Expands an RFC 5545 RRULE (FREQ DAILY/WEEKLY/MONTHLY/YEARLY, INTERVAL, COUNT, UNTIL, BYDAY with ordinals, BYMONTHDAY, BYMONTH, BYSETPOS, WKST; DTSTART with TZID; EXDATE) or a crontab(5) expression into up to 366 occurrences in a time zone, with the UTC instant of each, DST gap or overlap flags, caller blackout dates, a plain-English reading, and optionally the occurrences where it collides with a second rule. COUNT is applied before EXDATE removal, invalid dates (Feb 30) are skipped, a time in a gap is read with the pre-gap offset and an overlap uses its first occurrence (RFC 5545 3.3.5). Hourly/minutely FREQ, BYHOUR, BYYEARDAY, BYWEEKNO, RDATE, EXRULE, Quartz cron extensions and @macros return `unsupported`. Never reads the clock: the window starts at `from` (or DTSTART).\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"business","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/recurrence-expand","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["kind","rule"],"properties":{"kind":{"type":"string","enum":["rrule","cron"]},"rule":{"type":"string","maxLength":800,"description":"rrule: 'DTSTART;TZID=America/New_York:19970902T090000\\nRRULE:FREQ=DAILY;COUNT=10\\nEXDATE;TZID=America/New_York:19970903T090000' or just 'FREQ=...' with dtstart. cron: '*/15 9-17 * * 1-5' (dom and dow both restricted match if either does)."},"dtstart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$","maxLength":30,"description":"Local DTSTART when the rule text has none."},"timeZone":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+){0,2}$","maxLength":64,"description":"IANA zone for local times (required for cron; for rrule unless DTSTART has TZID or Z)."},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$","maxLength":30,"description":"Local start of the output window; required for cron, default DTSTART for rrule."},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$","maxLength":30,"description":"Local end of the window, inclusive."},"limit":{"type":"integer","minimum":1,"maximum":366,"description":"Maximum occurrences returned (default 20)."},"exdates":{"type":"array","maxItems":200,"items":{"type":"string","maxLength":30},"description":"Extra excluded local date-times (YYYY-MM-DDTHH:MM[:SS]) or dates (YYYY-MM-DD, excludes that day)."},"blackouts":{"type":"array","maxItems":50,"items":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","maxLength":10},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","maxLength":10}}},"description":"Inclusive local date ranges to drop (holidays, freezes)."},"durationMinutes":{"type":"integer","minimum":0,"maximum":43200,"description":"Occurrence length, for conflict overlap."},"other":{"type":"object","required":["kind","rule"],"description":"A second rule to compare; conflicts are occurrences whose intervals overlap (equal instants when both durations are 0).","properties":{"kind":{"type":"string","enum":["rrule","cron"]},"rule":{"type":"string","maxLength":800},"dtstart":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[Tt ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?$","maxLength":30},"timeZone":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+){0,2}$","maxLength":64},"durationMinutes":{"type":"integer","minimum":0,"maximum":43200}}}}},"example":{"kind":"rrule","rule":"DTSTART;TZID=America/New_York:19970902T090000\nRRULE:FREQ=DAILY;COUNT=10","limit":10}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"occurrences":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"local":{"type":"string"},"utc":{"type":"string"},"dst":{"type":"string","enum":["gap","overlap"]}}}},"count":{"type":"integer"},"description":{"type":"string"},"timeZone":{"type":"string"},"excluded":{"type":"array","items":{"type":"object","properties":{"local":{"type":"string"},"reason":{"type":"string"}}}},"moreAvailable":{"type":"boolean"},"scanCapped":{"type":"boolean"},"conflicts":{"type":"array","items":{"type":"object","properties":{"aIndex":{"type":"integer"},"bIndex":{"type":"integer"},"aUtc":{"type":"string"},"bUtc":{"type":"string"}}}},"comparedThroughUtc":{"type":"string"},"reason":{"type":"string"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/recurrence-expand/","docsJson":"https://agents.writerslogic.com/docs/recurrence-expand.json","sample":"https://agents.writerslogic.com/api/v1/samples/recurrence-expand","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}