📅 Scheduler API

Lightweight, Stateless Schedule Pattern Calculation Service

Welcome to the Scheduler API!

This is a pure computation service for schedule pattern calculation and validation. It provides:

Abstract Patterns: Human-readable scheduling patterns like @daily, @tomorrow@noon, @inaweek+2d
Suffix Arithmetic: Offset a day segment against a reference point — @today+1d@6:00@once is "tomorrow at 6am", and combined with reference_timestamp gives you "N days after an arbitrary event"
Time-Range Constraints: A third pattern segment can confine runs to a window — @daily@hourly@5am-7pm, @daily@hourly@0530-1945, or a combo like @daily@hourly@5am-7am,12pm,5pm-9pm (overnight ranges that wrap midnight are not yet supported)
Cron Expression Support: Parse and calculate next run times for standard 5-field cron expressions (0 2 * * *)
Fixed Datetime Scheduling: One-time execution at specific datetime values
Timezone Awareness: Full timezone support for accurate calculation across regions
Pattern Validation: Validate abstract patterns, cron expressions, datetime strings, and timezones
Cron/At Export: Convert abstract patterns into crontab lines or at commands
Spaced Repetition: Review-history-driven scheduling (SM-2, FSRS-6, HLR) in its own endpoint namespace
Helpful Error Messages: Descriptive validation errors with examples to guide API users

Note: This is a stateless service - no persistence, no database, just pure calculation.

View machine-readable API spec (/api.json)

API Endpoints

Timezone for examples: Rewrites the timezone field in every request body below that has one.

GET /health

Service health check and version metadata.

Try it out:

Open /health

POST /calculate

Comprehensive endpoint for schedule calculation and validation. Provides identical functionality to /validate.

Try it out:

Response:

POST /calculate-next-run

Calculate next run times for an abstract pattern (e.g., @daily, @tomorrow@noon, @inaweek+2d).

Try it out:

Response:

POST /calculate-next-run-cron

Calculate next run times for a cron expression (5-field format: minute hour day month day-of-week).

Try it out:

Response:

POST /pattern-to-scheduling

Convert abstract patterns to cron expressions or at commands. Recurring patterns export as cron, one-time patterns export as at commands.

Try it out:

Response:

POST /validate

Validate cron expressions, datetime strings, schedule patterns, or timezones.

Try it out:

Response:

GET /aliases

Discover all available pattern aliases and format specifications.

Try it out:

Open /aliases

GET /vocabulary

Complete reference guide for all hardcoded vocabularies and mappings. Includes day, time, and recurrence terms plus their numeric mappings for cron/at export.

Try it out:

Open /vocabulary

Spaced Repetition

Its own namespace, deliberately separate from the calendar-pattern endpoints above. These compute the next review time from review history rather than from a fixed calendar rule. Fully stateless — the caller owns the algorithm state and passes it back on each call. Nothing is persisted server-side.

POST /spaced-repetition/sm2/next-review

SM-2 (SuperMemo 2, Wozniak 1987). Stateless: caller owns and passes repetitions/ease_factor/interval_days between calls, nothing persisted server-side.

Try it out:

Response:

POST /spaced-repetition/fsrs6/next-review

FSRS-6 (Ye). Uses Anki's published 21-parameter default weights; no caller-supplied parameter override in this build. Stateless: caller owns and passes stability/difficulty/last_review between calls.

Try it out:

Response:

POST /spaced-repetition/hlr/next-review

Half-Life Regression (Settles & Meeder, Duolingo 2016), inference only. IMPORTANT: the weights shipped here are the paper's hand-derived Leitner-equivalent special case (theta = {bias:0, right:+1, wrong:-1}), not a trained model — Duolingo never published fitted interaction-feature weights. See HlrService docblock and backlog.md for the low-priority revisit item.