FlowynBETA
LoginSign up

Schedules

Stores a cron expression, a timezone, and an HTTP request. Each occurrence creates an ordinary durable job with its own attempts and retries. Missed occurrences are skipped, not backfilled.

What schedules does

Stores a cron expression, a timezone, and an HTTP request. Each occurrence creates an ordinary durable job with its own attempts and retries. Missed occurrences are skipped, not backfilled.

When to use schedules

  • Nightly reconciliation
  • Periodic syncs
  • Waking an agent on a timetable

Authentication

Send an API key as a bearer token. Keys are shown once, belong in a server environment, and are bound to one environment: flw_test_ keys act in test and flw_live_ keys in live.

http
Authorization: Bearer flw_test_••••

Endpoint

http
POST https://api.flowyn.dev/v1/schedules

Request

Send an Idempotency-Key so a retried request cannot create a duplicate. The body is JSON.

curl -X POST https://api.flowyn.dev/v1/schedules \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-report" \
  -d '{
    "name": "Nightly report",
    "cron": "0 2 * * *",
    "timezone": "Europe/Berlin",
    "method": "POST",
    "url": "https://api.example.com/reports/nightly",
    "max_attempts": 3
  }'

Response

Flowyn returns HTTP 200. The response is abridged here; the OpenAPI document lists every field.

Response
{
  "id": "d4a1b7c9-6e2f-4c8a-b3d5-9f1e0a2c4b76",
  "environment": "test",
  "name": "Nightly report",
  "cron": "0 2 * * *",
  "timezone": "Europe/Berlin",
  "method": "POST",
  "url": "https://api.example.com/reports/nightly",
  "max_attempts": 3,
  "paused": false,
  "catch_up": "skip",
  "overlap_policy": "skip",
  "next_run_at": "2026-10-01T00:00:00Z",
  "last_run_at": null
}

Lifecycle

  1. POST /v1/schedules stores the schedule. Flowyn computes next_run_at.
  2. At each occurrence Flowyn creates a durable HTTP job from the schedule's request.
  3. The job runs with its own attempts and retries.
  4. With the default overlap_policy: skip, an occurrence is skipped while the previous one is still running.

Status values

StatusMeaning
active (paused: false)Creates a job at each occurrence.
paused (paused: true)Kept, creates nothing.

Retries

Retries belong to each generated job and follow the job retry policy.

Idempotency

Send Idempotency-Key on create.

Errors

StatustypeMeaning
400invalid_requestThe body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large).
401unauthorizedMissing, malformed, or revoked API key.
402billing_errorThe monthly credit allowance is used (credit_limit_exceeded). Reads keep working.
403forbiddenThe key lacks the ability this call needs (ability_required).
404not_foundThe id does not exist in this environment.
409conflictFor example idempotency_mismatch: the Idempotency-Key was used with a different body.
422invalid_requestA field value is out of range, for example invalid_timeout.
429rate_limitedToo many requests (rate_limit_exceeded). Wait for Retry-After seconds.
5xxserver_errorFlowyn failed. The body carries an error_id to quote to support.

Limits

  • Five-field cron and an IANA timezone
  • catch_up is skip: missed occurrences are not backfilled
  • Same request limits as HTTP jobs

Read it back

Keep the id and read the resource whenever you need its current state.

bash
curl https://api.flowyn.dev/v1/schedules/d4a1b7c9-6e2f-4c8a-b3d5-9f1e0a2c4b76/occurrences \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Next step

Watch the target with a Monitor or a Heartbeat.