Schedules

A schedule is a registered intention to fire a webhook at a future time, optionally recurring. It is the simplest of the four primitives and the foundation the others lean on: you hand us a moment (or a repeating rule) and a webhook_url, and at that moment we POST to your endpoint. Nothing runs your code in between — a schedule is a clock, not a job queue.

Reach for a schedule when the cue is the time itself: "call this agent back in three days", "post the digest every Monday at 09:00". Reach for a deadline instead when the thing you care about is an obligation with a completion state and escalation — "the certificate is due March 14, warn me a week ahead, and keep nagging if it lapses". A schedule fires and forgets; a deadline tracks whether the work got done. When in doubt: if you would ever want to mark it "done", it's a deadline.

How schedules behave

A schedule is either one-shot or recurring:

• One-shot — you give a single fire_at timestamp (must be in the future). It fires once and is finished.
• Recurring — you give a cron expression (recurrence) and an IANA timezone (recurrence_tz, e.g. Europe/London). We evaluate the cron in that timezone, so a 0 9 * * MON schedule stays at 9am local across daylight-saving shifts. Each occurrence is its own record; the ones sharing a rule form a series joined by a recurrence_series_id.

A recurring series advances by spawning its successor when an occurrence resolves — whether it fired successfully or failed to deliver. The next occurrence is computed from the moment it actually fired, so a backlog never snowballs into a burst of catch-up callbacks. There is always exactly one pending occurrence of a live series at a time.

Each schedule carries a status:

"Fired" means we dispatched the webhook, not that your endpoint acknowledged it. Delivery has its own independent retry/backoff/dead-letter pipeline — 5xx/timeouts are retried with exponential backoff, 4xx are not. That contract is owned by Webhooks & signing; a recurring series keeps advancing regardless of any single delivery's fate.

Create a schedule

Every create is idempotent: pass an idempotency key and a retried create returns the original schedule instead of making a second one. See Idempotency for how to choose keys.

# One-shot: fire once, three days out
curl https://aigears.example.com/v1/schedules/ \
  -H "Authorization: Bearer aigears_live_..." \
  -H "Idempotency-Key: call-me-back-42" \
  -H "Content-Type: application/json" \
  -d '{
    "fire_at": "2026-07-06T09:00:00Z",
    "webhook_url": "https://hooks.example.com/aigears",
    "payload": {"task_id": "42"}
  }'

# Recurring: every Monday at 09:00 London time
curl https://aigears.example.com/v1/schedules/ \
  -H "Authorization: Bearer aigears_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recurrence": "0 9 * * MON",
    "recurrence_tz": "Europe/London",
    "webhook_url": "https://hooks.example.com/aigears"
  }'

Inspect schedules

Listing shows one row per series (the live occurrence stands in for its rule), while fetching a single schedule gives you its full state plus its delivery history — every attempt we made to reach your endpoint, with status codes.

curl "https://aigears.example.com/v1/schedules/?status=pending" \
  -H "Authorization: Bearer aigears_live_..."

Cancel a schedule

You can only cancel a schedule while it is pending. Cancelling one that has already fired, failed, or been cancelled returns a 409 — there is nothing left to stop.

There is one rule worth internalising for recurring schedules. A live series is represented by its single pending occurrence, and cancelling that occurrence terminates the series — no successor is spawned, so the whole recurrence stops. There is no separate "delete the series" action; cancel the pending occurrence and the rule is done.

curl -X POST https://aigears.example.com/v1/schedules/01J9Z8XKQR.../cancel/ \
  -H "Authorization: Bearer aigears_live_..."

The webhook you receive

When a schedule fires, we POST a schedule.fired event to its webhook_url. Inside the standard signed envelope, the data payload is small — an id and the payload you registered:

{
  "event_type": "schedule.fired",
  "data": {
    "schedule_id": "01J9Z8XKQR...",
    "payload": { "task_id": "42" }
  }
}

The envelope shape, the X-AIGears-Signature header, and the retry/dead-letter rules are the same for every primitive and are documented once in Webhooks & signing. For the how-to of standing up a receiver and verifying the signature, see Receiving webhooks. Your handler must be idempotent on event_id, because delivery is at-least-once.

Limits

Creating a schedule counts against your plan's flow limit (the number of callbacks you can register per month). Recurring occurrences that we spawn automatically do not cost extra — only the create you initiate is metered, so a weekly schedule costs one, not fifty-two. Reads and inspections are never metered. The per-tier numbers, and what happens when you reach a limit (free tiers are capped hard; paid tiers get a soft grace window), live in Limits & tiers.

Related examples

• Remind me in three days
• Send the weekly report