Schedules API

Schedules provide org-scoped cron execution for saved scripts.

Endpoints

• GET /api/schedules list schedules for the caller org
• POST /api/schedules create a schedule
• GET /api/schedules/{id} fetch schedule detail and recent run history
• PUT /api/schedules/{id} update schedule fields
• DELETE /api/schedules/{id} soft-disable by default (?hard=true to hard-delete)
• POST /api/schedules/execute execute due schedules for the authenticated org context
• GET|POST /api/cron/scheduled-runs execute due schedules with cron secret auth

Create payload fields

• name, scriptId, agentId, cronExpression are required.
• Optional controls:
  • timezone
  • enabled
  • variables
  • vaultKeys
  • maxRuntimeMinutes
  • maxRetries
  • retryDelaySeconds
  • concurrencyLimit
  • idempotencyWindowMinutes

Cron and payload constraints are validated with Zod plus cron-parser checks.

Runtime notes:

• maxRuntimeMinutes defaults to 720 (12 hours)
• maxRuntimeMinutes supports values up to 1320 (22 hours)

Execute request

POST /api/schedules/execute body:

{
  "dryRun": false,
  "force": false,
  "limit": 10,
  "scheduleId": null
}

Constraints:

• limit: 1..100
• force: true requires scheduleId

Security and access

• Session auth and API key auth are both supported.
• Viewer role is read-only; create/update/delete/execute return 403.
• Script and agent ownership are validated against organization scope before writes.

Reliability guards

Execution enforces:

• global advisory lock for due-schedule scans plus per-schedule locks for individual execution
• schedule concurrency limit
• idempotency window checks
• billing gate (canLaunchRuns)
• agent readiness checks with auto-start for stopped/offline agents
• vault secret resolution before dispatch

Use together with /api/cron/stale-jobs to recover timed-out work and keep schedules healthy.