Skip to main content
POST
Add a schedule to the project

Authorizations

Authorization
string
header
required

Clerk API key. Create one from your account settings under API Keys.

Path Parameters

id
string<uuid>
required

Body

application/json
name
string | null

Optional label (up to 80 characters); null clears it.

enabled
boolean
frequency
enum<string>
Available options:
daily,
weekly,
monthly
hour
integer
deprecated

Legacy: a UTC hour. Moves the schedule to the next occurrence of that hour and repeats it in UTC. Ignored when startsAt is set; prefer startsAt + timezone.

Required range: 0 <= x <= 23
startsAt
string<date-time>

The first run, as ISO 8601 with its UTC offset (e.g. 2026-11-02T09:00:00-05:00). Within the next year.

timezone
string

IANA time zone the schedule repeats in (e.g. America/New_York), so runs keep their wall-clock time across daylight saving changes. Send it with startsAt: changing an existing schedule's zone without a start time is a 400. Defaults to the current zone, or UTC for a new schedule.

scope
object

What the schedule runs. Each field is optional.

Response

Created

schedules
object[]
required

The project's schedules, oldest first.

draft
object
required

The defaults a new schedule starts from.

multipleSchedulesEnabled
boolean
required

Whether the plan allows more than one active schedule per project.