---
title: "Create a worker schedule"
method: POST
path: "/api/workers/{workerId}/schedules"
tags: ["Schedules"]
---

# Create a worker schedule

`POST /api/workers/{workerId}/schedules`

Schedule a worker instruction for a future or recurring run.

## Path parameters

- `workerId` string, required

## Request body

- CreateWorkerScheduleRequest
  - `input` string, required
  - `budget` 'low' | 'standard' | 'high' | 'unlimited'
  - `when` union, required
    - ScheduledWhen
      - `type` 'scheduled', required
      - `date` string, required
    - DelayedWhen
      - `type` 'delayed', required
      - `delayInSeconds` integer, required
    - CronWhen
      - `type` 'cron', required
      - `cron` string, required
    - IntervalWhen
      - `type` 'interval', required
      - `intervalSeconds` integer, required

## Response `201`

Created worker schedule.

- union
  - ScheduledWorkerSchedule
    - `id` string, required
    - `input` string, required
    - `budget` 'low' | 'standard' | 'high' | 'unlimited', required
    - `nextRunAt` string, date-time, required
    - `type` 'scheduled', required
  - DelayedWorkerSchedule
    - `id` string, required
    - `input` string, required
    - `budget` 'low' | 'standard' | 'high' | 'unlimited', required
    - `nextRunAt` string, date-time, required
    - `type` 'delayed', required
    - `delayInSeconds` integer, required
  - CronWorkerSchedule
    - `id` string, required
    - `input` string, required
    - `budget` 'low' | 'standard' | 'high' | 'unlimited', required
    - `nextRunAt` string, date-time, required
    - `type` 'cron', required
    - `cron` string, required
  - IntervalWorkerSchedule
    - `id` string, required
    - `input` string, required
    - `budget` 'low' | 'standard' | 'high' | 'unlimited', required
    - `nextRunAt` string, date-time, required
    - `type` 'interval', required
    - `intervalSeconds` integer, required

## Other responses

- `401` — Unauthorized.
- `402` — Payment required.
- `403` — Forbidden.
- `429` — Rate limit exceeded.
- `500` — Internal server error.

## Changes

- **2026-05-12** `e7f2a4252e77` — 1 breaking, 1 info
  - the `when/oneOf[#/components/schemas/ScheduledWhen]/date` request property's minLength was increased from `0` to `1`
  - the `when/oneOf[#/components/schemas/ScheduledWhen]/date` request property type/format was generalized from `string`/`date-time` to `string`/``
- **2026-05-11** `689cce060c12` — 8 breaking, 8 info
  - the `type` request property const value `cron` was added
  - the `type` request property const value `delayed` was added
  - the `type` request property const value `interval` was added
  - the `type` request property const value `scheduled` was added
  - …12 more

[Change history](https://skmtc.dev/ramensoft/apis/handinger-api/changes/api/workers/:workerId/schedules/post.md)

---

[API](https://skmtc.dev/ramensoft/apis/handinger-api.md) · [All operations](https://skmtc.dev/ramensoft/apis/handinger-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ramensoft/handinger-api/revisions/95b6b61a63ef/schema)