---
title: "POST /experimental/scheduled-runs"
method: POST
path: "/experimental/scheduled-runs"
tags: ["Scheduled Runs"]
---

# POST /experimental/scheduled-runs

`POST /experimental/scheduled-runs`

Creates a scheduled run 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
  - `metadata` object
  - `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
  - `snapshot` string — Commit SHA or tag pinning the repo snapshot for this run. Pins the checked-out repository, not the sandbox runtime image. Use `sandboxSnapshot` for the latter.
  - `sandboxSnapshot` string — Operational override selecting the sandbox runtime image the launch run is created from. Distinct from `snapshot`, which pins the checked-out repository. When omitted the run falls back to the configured default.
  - `workdir` string
  - `agent` string
  - `model` string
  - `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.

## Response `201`

Default Response

- object
  - `links` object, required
    - `self` string, uri, required
  - `data` object, required
    - `id` string, uuid, required
    - `type` 'scheduled-run', required
    - `attributes` object, required
      - `status` union, required
        - 'active'
        - 'paused'
      - `cron` string, required
      - `timezone` string, required
      - `label` 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

---

[API](https://skmtc.net/tessl/apis/tessl-api.md) · [All operations](https://skmtc.net/tessl/apis/tessl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tessl/tessl-api/versions/fbb186825642/schema)