Cloudharness Dev Portal
CloudCron Schedule Next API

Schedule

Endpoint:https://api.cloudharness.com

Schedule computation operations for CRON expressions with timezone support.

Current phase supports 5-field CRON expressions only. Future phases will add business macros, plain language parsing, and holiday filtering.

Compute next CRON execution time

POST
https://api.cloudharness.com
/v1/schedule/next

Computes the next execution time for a given CRON expression with timezone support.

Supported Features:

  • 5-field CRON expressions only (minute hour day_of_month month day_of_week)
  • IANA timezone support with DST ambiguity policies
  • Time-based search horizon (5 years from 'from' time)

Not Implemented (501 responses):

  • Plain language input (plain field)
  • Holiday filtering (except holidays.use='none')
  • Business macros in this MVP phase

Error Codes:

  • 400 BAD_REQUEST: Malformed JSON, missing required fields, Ajv validation failures
  • 422 INVALID_CRON: Invalid CRON expression (seconds field, Quartz tokens like ?, L, W, #)
  • 422 INVALID_TIMEZONE: Invalid IANA timezone identifier
  • 422 NO_FUTURE_OCCURRENCE: No future execution within search horizon (details.horizonYears=5)
  • 422 DST_AMBIGUOUS: Ambiguous time due to DST fall-back with ambiguityPolicy='error'
  • 422 DST_NON_EXISTENT: Non-existent time due to DST spring-forward with ambiguityPolicy='error'
  • 501 NOT_IMPLEMENTED: Plain language input, holiday filtering, or macros like @yearly, @monthly, @daily provided

Note: Rate limiting and authentication (401/429) are handled by the Zuplo API Gateway. The function does not set rate-limit headers (X-RateLimit-*) in its responses.

Compute next CRON execution time › Headers

  • Authorizationstring · required

    The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Compute next CRON execution time › Request Body

  • cronstring · cron5 · required

    5-field CRON expression (minute hour day_of_month month day_of_week).

    Format: minute hour day_of_month month day_of_week

    • minute: 0-59
    • hour: 0-23
    • day_of_month: 1-31
    • month: 1-12
    • day_of_week: 0-7 (0 or 7 is Sunday)

    Supported operators: *, -, ,, / Not supported: Quartz tokens (?, L, W, #), seconds field (6+ fields)

  • tzstring · iana-tz

    IANA timezone identifier for execution time calculation. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

    Default: UTC
  • fromstring · date-time · pattern: .*Z$

    Starting time for next occurrence calculation in ISO8601 UTC format. Must end with 'Z' suffix. If not provided, defaults to current time.

  • ambiguityPolicystring · enum

    Policy for handling DST ambiguity when local times are non-existent (spring-forward) or ambiguous (fall-back).

    • first-valid: Use the first valid time (default)
    • second-valid: Use the second valid time
    • error: Return error for ambiguous times
    Enum values:
    first-valid
    second-valid
    error
    Default: first-valid
  • macrosboolean

    Enable business macros processing. Currently not implemented in MVP. Future phases will support @EOM, @EOQ, @semi-monthly, etc.

    Default: true
  • plainstring

    Plain language schedule input (e.g., "Every Monday at 9am").

    Not implemented in MVP - Sending this field returns 501 NOT_IMPLEMENTED. Will be supported in Phase 6.

  • holidaysobject

    Holiday configuration for filtering execution times. Currently only use: 'none' is supported.

  • returnstring · enum · deprecated · required

    DEPRECATED: This parameter is deprecated and ignored. Both nextIso and nextDate are always returned regardless of this parameter's value.

    Previously specified which timestamp formats to include in the response:

    • iso: Only nextIso field (ISO8601 with timezone offset)
    • date: Only nextDate field (calendar date in target timezone)
    • both: Both nextIso and nextDate fields (default)

    For backwards compatibility, this field is still accepted but has no effect on the response format.

    Enum values:
    iso
    date
    both
    Default: both

Compute next CRON execution time › Responses

Successfully computed next execution time

  • nextIsostring · date-time · required

    Next execution time in ISO8601 UTC format. Always returned regardless of deprecated 'return' parameter.

  • nextDatestring · date · required

    Next execution date in YYYY-MM-DD format in the requested timezone. Always returned regardless of deprecated 'return' parameter.

  • schedlstring · required

    Canonical SCHEDL (Schedule Language) representation of the schedule. Format: " tz="

  • expandedCronstring · required

    Normalized 5-field CRON string with single spaces when input is valid. Null if normalization cannot be produced, with warning added to warnings array.

  • explanationstring · required

    Human-readable explanation of the schedule using 24-hour format. Format: "At HH:mm on "

  • warningsstring[] · required

    Array of human-readable warning codes about schedule processing. May include DST adjustments, deprecated parameter warnings, normalization fallback, etc.

Health