Core concepts

SchedStack’s delivery hierarchy is three core objects. Learn them once and the rest of the API reads itself. (A fourth object, the optional reusable endpoint profile, is a saved destination a schedule can reference by endpoint_id instead of an inline endpoint — not part of the delivery flow below.)

1. A schedule is your instruction: this destination, at this time (or on this recurrence). You create one with POST /v1/schedules.

2. A schedule produces deliveries — one per occurrence. A one-shot schedule produces one delivery; a recurring schedule produces a new delivery for each fire of its cron.

3. Each delivery makes one or more attempts — individual outbound HTTP requests to your endpoint. The first attempt that gets a 2xx ends the delivery; failures are retried under the delivery’s retry_policy.

schedule ──┬─► delivery (occurrence) ──┬─► attempt 1  (HTTP POST → your endpoint)
           │                           ├─► attempt 2  (retry)
           │                           └─► attempt 3  (succeeds → delivery done)
           └─► delivery (next occurrence, recurring only) …

The guarantee: no silent loss

Once SchedStack accepts a delivery (your POST returned 2xx), that delivery is durable. It will not vanish, and it will not stall unobserved. It ends in exactly one terminal state, and that outcome is recorded and readable on the delivery:

• succeeded — an attempt got a 2xx from your endpoint.
• dead_letter — retries were exhausted without a 2xx. The delivery is parked, not dropped; you can inspect it and replay it.
• expired — the delivery’s ttl elapsed before it could land.
• canceled — you canceled the schedule (or the delivery) before it completed.

There is no fifth outcome and no “lost” outcome. If you accepted it, you can always find out what happened to it.

Where to read state

Non-terminal deliveries are live work; terminal deliveries are recorded history. Both are queryable via the deliveries endpoints — see the API reference. A delivery never silently leaves this set.

At-least-once, made safe

SchedStack is at-least-once, not exactly-once. A delivery can legitimately hit your endpoint more than once — a network blip after your 2xx, a lease handoff, a replay. That is the honest tradeoff of durable delivery, and we hand you the two tools to make it safe:

• Signature — when your project (or the endpoint profile) has at least one active signing secret, every outbound request carries a Sched-Signature HMAC so your receiver can prove the request came from SchedStack before acting on it. Without an active secret the header is omitted and the request is sent unsigned, so configure a secret before you rely on verification. This is the signature-verification guide — read it before you ship a receiver.
• Idempotency — every attempt for a given delivery carries the same stable outbound Idempotency-Key — the schedule’s idempotency_key if you set one, otherwise the delivery’s ID. Dedup on it and a redelivered occurrence is a no-op on your side.

So the contract is split honestly: SchedStack guarantees at-least-once with no silent loss; you guarantee effectively-once by verifying the signature and deduping on the key. Neither side can do the other’s half.

Two idempotency mechanisms — don’t confuse them

• The request header Idempotency-Key on your POST /v1/schedules deduplicates the API call itself (safe retries of schedule creation). Send the same key with the same body and SchedStack replays the original response instead of creating a second schedule.
• The body field idempotency_key rides along to your receiver: it becomes the value of the outbound Idempotency-Key header, stable across every attempt of the occurrence, so your receiver can dedup redeliveries. Omit it and SchedStack uses the delivery’s ID as that value.

The request header guards creation; the body field guards receiver-side delivery. See idempotency.

Schedules

A schedule is created live or in test mode (the API key prefix — sk_live_… vs sk_test_… — decides; the two never mix). It is either a one-shot (delay, fire_at, or local_fire_at + timezone) or recurring (cron, with DST-correct local-time recurrence — see recurring schedules).

One-shot (relative)

curl -X POST https://api.schedstack.com/v1/schedules \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"endpoint":"https://acme.dev/hook","delay":"24h"}'

One-shot (absolute, local)

curl -X POST https://api.schedstack.com/v1/schedules \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://acme.dev/hook",
    "local_fire_at": "2026-07-01T09:00:00",
    "timezone": "America/New_York"
  }'

Recurring (cron)

curl -X POST https://api.schedstack.com/v1/schedules \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://acme.dev/hook",
    "cron": "0 9 * * 1-5",
    "timezone": "America/New_York"
  }'

Schedule states

State	Meaning
active	The schedule is live. One-shots have a pending delivery; recurring schedules keep producing them.
paused	You paused it. Pending deliveries are held — not fired, not lost — until you resume.
canceled	You canceled it. Outstanding deliveries are stopped; this is terminal for the schedule.

Transitions are driven only by you, via pause / resume / cancel — active → paused → active, or active|paused → canceled.

completed is in the enum, but the engine does not use it

The API’s schedule-state enum includes a completed value, but the engine does not transition fired one-shots to completed. A one-shot stays active while its single delivery runs; you observe the delivery’s terminal state to know the outcome. Don’t poll the schedule for completed — it won’t appear. Read the delivery instead.

Deliveries

A delivery is one occurrence of a schedule firing. It moves through a small state machine. Non-terminal states live on the active delivery; the four terminal states are the recorded outcome.

State	Terminal?	Meaning
scheduled	—	Created and waiting for its fire time.
claimed	—	A dispatcher node has it and is sending the HTTP request right now. This single state spans the whole send (there is no separate “in-flight” or “sending” state).
retry_scheduled	—	The last attempt failed retryably; the next attempt is queued for a later time.
paused	—	The parent schedule was paused while this delivery was outstanding.
succeeded	✅	An attempt got a 2xx.
dead_letter	✅	Retries exhausted without success. Inspect and replay.
expired	✅	The ttl elapsed before the delivery could land.
canceled	✅	Canceled before it completed.

States you might expect but won’t find

There is no in_flight state — claimed covers the active send. And deferred is not a persisted state; deferral is internal scheduling, never something you observe on a delivery. Build dashboards and alerts around the eight states above, nothing else.

Attempts

An attempt is a single HTTP request to your endpoint, numbered from 1. Every attempt carries the delivery’s reserved headers so your receiver can authenticate and dedup:

Header	Value
Sched-Delivery-Id	The delivery’s stable ID.
Sched-Attempt	The attempt number (1, 2, …).
Sched-Timestamp	Unix seconds when the request was signed.
Sched-Signature	HMAC over the payload, format t=…,v1=… (supports key rotation overlap). Present only when an active signing secret exists; omitted otherwise (request sent unsigned).
Idempotency-Key	The schedule’s idempotency_key if you set one, otherwise the delivery ID — stable across every attempt of this occurrence either way. Dedup on it.

These headers are reserved: you cannot override Sched-* or Idempotency-Key from your schedule’s own headers. Each attempt is classified by its result:

Outcome	What it means	What SchedStack does next
success	A 2xx response.	Delivery → succeeded. Done.
retryable	A 5xx, 429, timeout, or connection error.	Schedule the next attempt per retry_policy; delivery → retry_scheduled. When retries run out → dead_letter.
terminal	A non-retryable result (most 4xx, plus 3xx redirects and blocked/SSRF-rejected destinations).	Stop. Delivery → dead_letter. No point retrying a request your endpoint rejected — or one we refused to send.

How many retryable attempts run, and the backoff between them, comes from the delivery’s retry_policy — see retries and backoff.

Status legend

A compact reference you can keep open while you build:

Object	Live (non-terminal)	Terminal
Schedule	active, paused	canceled
Delivery	scheduled, claimed, retry_scheduled, paused	succeeded, dead_letter, expired, canceled
Attempt (outcome)	—	success, retryable, terminal

Where to go next

• Quickstart — create a schedule, receive it, verify it, watch it land.
• Verifying signatures — the receiver-side trust centerpiece, with Node / Python / Go samples.
• Idempotency — request keys vs. delivery dedup, kept straight.
• Retries and backoff — the retry_policy and how attempts are classified.
• Dead-letter and replay — inspect parked deliveries and resend them.
• Recurring schedules — cron, timezones, and DST-correct firing.
• Lifecycle — pause, resume, cancel, reschedule.
• API reference — the full interactive REST reference.