Deadlines

A deadline is a dated obligation your agent has committed to — "renew the certificate by March 14", "file the report before the quarter closes". It is durable memory for the thing agents forget most: a future commitment made in one session that a later session has to honour. You hand us a due_at and a short summary, and we hold onto it, escalating through reminders as the date approaches and passes, until you mark it done.

A deadline looks superficially like a schedule, but they answer different questions. A schedule fires once at its moment and forgets; a deadline tracks whether the work got done and escalates if it doesn't. Reach for a deadline when any of these hold: you want reminders before and after the due date, not a single callback; some recipients are humans (reminder emails, not just a webhook); or the thing has a completion state you would want to mark "done". If you would never mark it done, it's a schedule.

How deadlines behave

Every deadline carries a due_at and a required summary — the human-readable label every dashboard row and reminder is keyed on. (A webhook_url is optional and can't stand in for the summary.) Around the due date, an escalation policy drives a series of reminders; see the next section.

A deadline's status is stored, not derived on read:

open and overdue together are the active set — the deadlines still on your plate, and the set the stock limit counts (see Limits, below).

Reminders go to destinations that live on the deadline itself, not inside the policy: an optional webhook_url (same shape as a schedule's) and notify_emails, a list of zero or more human recipients. A deadline may also carry an optional cron recurrence + IANA recurrence_tz; completing a recurring deadline spawns its successor (see below).

Escalation policies

An escalation policy is a small JSON document listing the reminder steps, each an offset relative to due_at and the channels it fires on. Offsets are signed ISO-8601 durations: negative is before due, P0D is the due date itself, positive is after. Channels are webhook, email, or both. One step may carry "repeat": "daily" to keep nagging once a day (usually the post-due step). This is the system default — warn at 30, 7, and 1 day out, on the due day, then daily once it lapses:

{
  "steps": [
    {"offset": "-P30D", "channels": ["webhook"]},
    {"offset": "-P7D",  "channels": ["webhook"]},
    {"offset": "-P1D",  "channels": ["webhook"]},
    {"offset": "P0D",   "channels": ["webhook"]},
    {"offset": "P1D",   "channels": ["webhook"], "repeat": "daily"}
  ]
}

When you create the deadline, the policy is materialised up front into one concrete reminder per (step × channel), anchored on the current due_at. Any step whose computed time is already in the past is skipped — a deadline you remember two days before it's due simply won't get its 30-day warning.

Two rules to internalise:

• A referenced channel must have a destination. If any step lists webhook, webhook_url is required; if any lists email, notify_emails must be non-empty. A channel with nowhere to send is a create-time validation error, never a silently dropped reminder.
• You can preview a policy before committing. POST /v1/deadlines/escalation-preview/ (and the live preview on the dashboard create form) returns the exact reminder fire-times for a due_at + policy. It's read-only: it creates nothing and costs no quota.

Remember a deadline

Every create is idempotent: pass an idempotency key and a retried create returns the original deadline instead of a duplicate. See Idempotency for choosing keys.

curl https://aigears.example.com/v1/deadlines/ \
  -H "Authorization: Bearer aigears_live_..." \
  -H "Idempotency-Key: renew-cert-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Renew the TLS certificate",
    "due_at": "2026-03-14T00:00:00Z",
    "webhook_url": "https://hooks.example.com/aigears",
    "notify_emails": ["[email protected]"],
    "escalation_policy": {
      "steps": [
        {"offset": "-P7D", "channels": ["webhook", "email"]},
        {"offset": "P0D",  "channels": ["webhook", "email"]},
        {"offset": "P1D",  "channels": ["email"], "repeat": "daily"}
      ]
    }
  }'

Query what's due

This is the payoff for agents that span sessions. A fresh agent instance, holding none of the context that created a deadline, can ask "what did past-me commit to?" and get back everything still active. That is the whole point of making deadlines durable: the commitment outlives the conversation that made it.

# What have I committed to in the next 30 days (plus anything already overdue)?
curl "https://aigears.example.com/v1/deadlines/query/?window=P30D" \
  -H "Authorization: Bearer aigears_live_..."

Complete, snooze, or cancel

Three actions move a live deadline. All three act only on an active (open or overdue) deadline; calling any of them on one that is already completed or cancelled returns a 409 — there's nothing left to act on.

• Complete — mark the obligation done. It's terminal, and it cancels any pending reminders. For a recurring deadline, completing the current occurrence advances the series: we spawn its successor at the next cron occurrence, sharing the rule, destinations, and policy.
• Cancel — call the obligation off. Also terminal; for a recurring deadline, cancelling terminates the series — no successor is spawned. This is the only way to stop a recurring deadline; there is no separate delete-series action.
• Snooze — push due_at forward to a new time. This returns an overdue deadline to open and rebuilds its reminders from the policy against the new date (past-due steps skipped, exactly as at create).

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

Notifications you receive

Each reminder that fires POSTs a deadline.escalation event to your webhook_url (and/or sends a reminder email to notify_emails, for email steps). Inside the standard signed envelope, the webhook data identifies the deadline and the specific reminder:

{
  "event_type": "deadline.escalation",
  "data": {
    "deadline_id": "01J9Z8XKQR...",
    "notification_id": "01J9Z8ABCD...",
    "due_at": "2026-03-14T00:00:00Z",
    "fire_at": "2026-03-07T00:00:00Z",
    "tags": [],
    "metadata": {}
  }
}

One event fires per materialised reminder — a step listing two channels yields two notifications, one per channel. 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 standing up a receiver and verifying the signature, see Receiving webhooks. Delivery is at-least-once, so make your handler idempotent on event_id.

Limits

The stock you're metered on is active deadlines — the count of open plus overdue deadlines at any moment. Completing or cancelling a deadline frees the slot; the reminders a deadline fires along the way are not separately metered, and reads and previews are never metered. The per-tier caps, and what happens when you reach one, live in Limits & tiers.

Related examples

• Renew the certificate
• The renewals agent