# Untimely Full Agent Context

Canonical site: https://untimely.app
Production API: https://untimely.app
Preview API: https://untimely-preview.bitspice.workers.dev
OpenAPI: https://untimely.app/openapi.json

## Product

Untimely schedules recurring events that should happen within humane windows rather than exact calendar slots. It is useful for reminders, prompts, and lightweight automations where the timing should stay bounded but not rigid.

Untimely supports two schedule modes:

- Random windows: choose an interval, frequency, days of week, and a start/end time window.
- Fixed time: choose a deterministic time, timezone, interval, and days of week.

Supported actions are EMAIL and WEBHOOK.

## API Key Workflow

API keys are created in dashboard settings by signed-in users. The key is shown once. Agents use existing keys by sending `Authorization: Bearer <UNTIMELY_API_KEY>`.

Use `Idempotency-Key` on `POST /api/events` so retries do not create duplicate events.

## Main API Routes

- `GET /api/events`: list recent events with schedule and run status.
- `POST /api/events`: create an event.
- `GET /api/events/{id}`: read one event status.
- `PATCH /api/events/{id}`: update an event.
- `DELETE /api/events/{id}`: delete an event.
- `GET /api/events/{id}/schedules/{scheduleId}`: inspect one schedule run and tool attempts.

## Random Event Example

```json
{
  "name": "Weekly random check-in",
  "interval": 7,
  "frequency": 2,
  "betweenTimeStart": "09:00",
  "betweenTimeEnd": "17:00",
  "daysOfWeek": [1, 2, 3, 4, 5],
  "actionType": "EMAIL",
  "content": "Pause and review the highest leverage task.",
  "contentType": "static"
}
```

## Webhook Action Example

```json
{
  "name": "Agent follow-up",
  "scheduleType": "deterministic",
  "interval": 7,
  "fixedTime": "09:30",
  "timezone": "America/Toronto",
  "daysOfWeek": [1],
  "actionType": "WEBHOOK",
  "content": "Run the weekly follow-up workflow.",
  "contentType": "static",
  "webhook": {
    "method": "POST",
    "url": "https://example.com/untimely-hook",
    "headers": [
      {"key": "Content-Type", "value": "application/json"}
    ],
    "body": "{\"source\":\"untimely\"}"
  }
}
```

## Comparison Positioning

Untimely can replace many scheduled HTTPS/webhook jobs that otherwise live in cron services or platform cron configuration. It adds flexible windows, email delivery, product-managed event history, API keys, and a calmer UI for schedules that users and agents need to create or adjust.

Use infrastructure cron when the scheduled unit must run inside a specific runtime with platform bindings, very frequent fixed execution, or deployment-owned configuration. Use monitoring tools when the action depends on telemetry, uptime checks, traces, SLOs, or synthetic test failures.

Important comparison pages:

- https://untimely.app/compare/untimely-vs-cron-job-org
- https://untimely.app/compare/untimely-vs-vercel-cron
- https://untimely.app/compare/untimely-vs-cloudflare-cron
- https://untimely.app/compare/untimely-vs-datadog-monitors