Schedules API

All schedule endpoints are project-scoped. The actions are enable / disable / trigger, not pause / resume.

List schedules

GET /api/v1/projects/{slug}/schedules

Role: viewer.

Query params: scheduler (e.g. celery-beat, apscheduler), enabled (bool), cursor, limit.

{
  "items": [
    {
      "id": "...",
      "project_id": "...",
      "name": "email.daily-digest",
      "scheduler": "celery-beat",
      "trigger_type": "cron",
      "trigger": {"minute": "0", "hour": "9", "day_of_week": "*"},
      "task": "email.send_daily_digest",
      "args": [],
      "kwargs": {"locale": "en-US"},
      "enabled": true,
      "last_run_at": "...",
      "next_run_at": "...",
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "next_cursor": "..."
}

Get schedule

GET /api/v1/projects/{slug}/schedules/{schedule_id}

Role: viewer.

Create schedule

POST /api/v1/projects/{slug}/schedules

Role: operator. CSRF-protected.

{
  "name": "email.daily-digest",
  "scheduler": "celery-beat",
  "trigger_type": "cron",
  "trigger": {"minute": "0", "hour": "9", "day_of_week": "*"},
  "task": "email.send_daily_digest",
  "args": [],
  "kwargs": {"locale": "en-US"},
  "enabled": true
}

args and kwargs JSON are each capped at 64 KiB.

Update schedule

PATCH /api/v1/projects/{slug}/schedules/{schedule_id}

Role: operator. CSRF-protected. Any subset of the create fields.

Delete schedule

DELETE /api/v1/projects/{slug}/schedules/{schedule_id}

Role: admin. CSRF-protected.

Enable / disable / trigger

POST /api/v1/projects/{slug}/schedules/{schedule_id}/enable
POST /api/v1/projects/{slug}/schedules/{schedule_id}/disable
POST /api/v1/projects/{slug}/schedules/{schedule_id}/trigger

Role: operator. CSRF-protected. trigger runs the underlying task once immediately and returns the resulting task id.

Fire history

GET /api/v1/projects/{slug}/schedules/{schedule_id}/fires

Role: viewer. Returns the schedule’s recent fire history (when it ran, what task id it produced, succeeded / failed).

Import / diff / resync

When the scheduler is authoritative (Celery beat, APScheduler), three colon-suffixed endpoints drive the sync workflow:

POST /api/v1/projects/{slug}/schedules:import
POST /api/v1/projects/{slug}/schedules:diff
POST /api/v1/projects/{slug}/schedules:resync

:import materialises the scheduler’s current schedules into the brain. :diff reports differences without writing. :resync reconciles drift in one direction (brain to scheduler or the reverse depending on the body).