Skip to main content
Version: 1.0.0

Scheduler Service API

Tenant-facing cron-as-a-service: schedule management, run history, and delivery-attempt inspection.

Semantics (public contract)​

  • Granularity: 1 minute. cron_expr is 5-field standard cron (no seconds field).
  • Run materialisation is exactly-once per (schedule_id, scheduled_for) occurrence.
  • Delivery is at-least-once. A run's action is attempted until it succeeds (HTTP 2xx for webhook, publish for event) or its retry policy is exhausted. Receivers MUST dedupe on X-Idempotency-Key (see the scheduleDelivery webhook below).
  • Timezones: IANA names, DST-aware. A local time skipped by spring-forward fires at the first valid instant after the gap; an ambiguous fall-back time fires once, at the first occurrence. scheduled_for is always the canonical, un-jittered planned instant.
  • Jitter is deterministic per schedule (hash(schedule_id) mod jitter_seconds) and moves only the actual fire time, never scheduled_for, the idempotency key, or history.

Authorization​

Every endpoint requires a tenant access token. Mutating endpoints — create, update, delete, pause, resume, and trigger — additionally require the tenant_admin role: a schedule is a standing outbound-HTTP capability of the platform, so an end-user token (role=user, minted for call participants) is refused with 403 forbidden. Read endpoints are available to any token carrying the tenant.

Rate limits​

POST /v1/schedules and POST /v1/schedules/{id}/trigger are rate limited per tenant (not per token subject, which a tenant mints freely). Exceeding a budget returns 429 rate_limited with a Retry-After header. Outbound delivery is additionally capped per tenant and per destination host; a delivery held back by that cap is postponed, not failed, and costs the run no attempt.

Standard errors​

All non-2xx responses use the Error envelope: { "error": { "code", "message", "request_id" } }. Common codes: validation_failed, invalid_cron, invalid_timezone, invalid_target_url, payload_too_large, interval_too_short, name_taken, schedule_limit_exceeded, not_found, invalid_state, rate_limited.

Pagination​

List endpoints take limit (default 50, max 200) and offset (default 0) and return a named array plus total.

Authentication​

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT