---
title: "POST /experimental/schedules"
method: POST
path: "/experimental/schedules"
tags: ["Schedules"]
---

# POST /experimental/schedules

`POST /experimental/schedules`

Creates a schedule that fires a launch run on a cron. The launch config is either copied from an existing launch run (`fromLaunchRunId`) or given inline (`skill`, `repo`, …); provide exactly one.

## Headers

- `Authorization` string

## Request body

- object
  - `workspaceName` string, required
  - `cron` string, required — Cron expression the schedule fires on, interpreted in `timezone`. Rejected if unparseable or if its tightest interval is under the minimum allowed.
  - `timezone` string — IANA timezone the cron is interpreted in (e.g. `America/New_York`). Defaults to `UTC`.
  - `fromLaunchRunId` string, uuid — Id of an existing launch run whose stored config this schedule copies. Mutually exclusive with the inline launch spec; provide exactly one. The caller must be able to `view` the launch run's workspace.
  - `label` string
  - `description` string
  - `metadata` object
  - `projectId` string, uuid — Project to attach the schedule to. Must be an active, editable project in the target org. When omitted, the project is inferred from the repository URL, and only when exactly one project in the workspace uses that repository.
  - `skill` string — The plugin to install and the skill to run. A value without a `file:` prefix means a registry ref (either a full `workspace/plugin[@version]` or a bare `plugin[@version]` name resolved across the workspaces the caller can see); a value with a `file:` prefix means a local plugin path inside the cloned repo (e.g. file:apps/cli/plugins/agent-enablement). Either form may carry a trailing `#skill` selector (e.g. `workspace/plugin@1.0.0#implement-ticket` or `file:apps/cli/plugins/agent-enablement#implement-ticket`) that installs the whole plugin and launches the one named skill; it is required when the plugin exposes more than one skill. This is a wire convention: the value is stored verbatim and interpreted downstream by the launch recipe.
  - `repo` string
  - `baseBranch` string
  - `sandboxSnapshot` string — Operational override selecting the sandbox runtime image the launch run is created from. When omitted the run falls back to the configured default.
  - `snapshotFamily` union — Selects the sandbox image family the run is created from (`base` for the standard recipe-runner image, `dev` for the Docker-capable variant). Resolved server-side to a concrete snapshot name — callers pick a capability set, not an internal image id. Mutually exclusive with `sandboxSnapshot`; providing both is a 400.
    - 'base'
    - 'dev'
  - `workdir` string
  - `agent` string
  - `model` string
  - `effort` union — Explicit reasoning effort for the selected agent. Omitted keeps the agent default. Unsupported agent and effort combinations are rejected before the run is created.
    - 'low'
    - 'medium'
    - 'high'
    - 'xhigh'
    - 'max'
  - `inputs` object — Skill-specific inputs forwarded to the launched skill, keyed by the skill's own placeholder names (e.g. ISSUE_IDENTIFIER, ISSUE_TITLE, ISSUE_DESCRIPTION).
  - `instructions` string — Free-text instructions appended to the skill prompt the launch agent runs, mirroring the local `--instructions` flag. Distinct from the structured `inputs` channel.
  - `environmentId` string, uuid — Id of a workspace environment whose sealed `.env` payload is opened server-side at each run. Must belong to the schedule workspace. Resolved live when each run fires, so environment edits take effect on subsequent runs and a deleted environment fails the launch.
  - `timeoutMs` integer — Per-run override, in milliseconds, for how long each fired run may work before it is timed out. Extends the default 50-minute timeout (3000000) up to 6 hours (21600000). Must be a whole number of minutes (a multiple of 60000). Omitted keeps the default.

## Response `201`

Default Response

- object
  - `links` object, required
    - `self` string, uri, required
  - `data` object, required
    - `id` string, uuid, required
    - `type` 'schedule', required
    - `attributes` object, required
      - `status` union, required
        - 'active'
        - 'paused'
      - `cron` string, required
      - `timezone` string, required
      - `label` string, nullable, required
      - `description` string, nullable, required
      - `createdBy` string, uuid, nullable, required
      - `createdAt` string, date-time, required

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

## Changes

- **2026-09-26** `b777eddaa913` — 1 warning, 1 info
  - removed the request property `snapshot`
  - added the new optional request property `projectId`
- **2026-09-23** `288d28ba107c` — 1 info
  - the `timeoutMs` request property's max was increased from `14400000.00` to `21600000.00`
- **2026-09-15** `d50a02b79ad3` — 2 info
  - added the optional property `error/code` to the response with the `403` status
  - added the optional property `error/url` to the response with the `403` status
- **2026-09-10** `e57a144d1cab` — 1 info
  - added the new optional request property `effort`
- **2026-09-04** `ffb03b5d287f` — 1 info
  - added the new optional request property `timeoutMs`

[Full history](https://skmtc.dev/tessl/apis/tessl-api/changes/experimental/schedules/post.md)

---

[API](https://skmtc.dev/tessl/apis/tessl-api.md) · [All operations](https://skmtc.dev/tessl/apis/tessl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tessl/apis/tessl-api/revisions/ee9b4e55fec4?raw)