---
title: "Replace a schedule"
method: PUT
path: "/v1/schedules/{scheduleId}"
---

# Replace a schedule

`PUT /v1/schedules/{scheduleId}`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/schedules/{scheduleId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Replaces a schedule's definition, starting a new generation. Takes the same four ways of saying when as a create, so a one-shot can be replaced by a recurring definition and the other way round. An omitted callback endpoint/data pair preserves the stored callback; sending `data` alone replaces the encrypted data for the current endpoint, and sending `endpoint` selects a verified endpoint in the same authority tuple. Sending `url` instead selects the endpoint at that address in the same tuple, creating one silently when there is none; creating needs `endpoints:write` as well, and the response's `endpointSigningSecret` says where its signing secret is revealed. Omitted `http` preserves HTTP settings. Its headers are a patch: `set` replaces a value, `keep` retains a configured value, `suppress` omits an endpoint default, and `remove` resumes inheritance. Explicit GET with no body clears a saved custom template; POST/PUT with `body: { mode: 'envelope' }` restores the structured callback. The occurrence planned under the old definition is settled `skipped_stale` and can never fire unless it was already in flight, in which case its immutable attempt is allowed to settle honestly; a fresh occurrence is planned under the new definition, and the old definition's series stops advancing. `lateness` is resolved afresh against the replacement recurrence: omit it for that kind's default, or state `skipAhead`, `catchUp`, and an optional `maxStalenessSeconds` override. The policy applies only before an occurrence's first attempt; a retry already in progress remains on its retry and give-up ladder. Send `If-Match` with the version you read to make this conditional; without it the replace is unconditional and the last writer wins. A cancelled or completed schedule cannot be replaced. `partitionKey` is fixed when the schedule is created: omit it to preserve the stored value or echo that exact value in a GET → modify → PUT flow. Adding, changing, or clearing it is refused as `invalid_request` with `/partitionKey` identified. `latencyClass` remains derived from the replacement recurrence when the caller omits it. Some calls need more: endpoints:write is required as well when the request names a `url` this project and environment has no endpoint at yet, and the call is refused `scope_missing` without it.

## Path parameters

- `scheduleId` string, required

## Headers

- `If-Match` string

## Request body

- object
  - `autoPauseAfterFailures` union: Consecutive failed runs before automatic pause: 1–100 or "never". Defaults to 5 on create; omission on replace preserves the setting. One-shot schedules are unaffected.
    - integer
    - 'never'
  - `http` object
    - `method` 'POST' | 'PUT' | 'GET'
    - `body` union
      - object
        - `mode` 'envelope', required
      - object
        - `mode` 'json', required
        - `value` Schema0, required (unresolved $ref)
    - `headers` union[]
      - union
        - object
          - `action` 'set', required
          - `name` string, required
          - `value` string, required
          - `secret` boolean
        - object
          - `action` 'keep', required
          - `name` string, required
        - object
          - `action` 'remove', required
          - `name` string, required
        - object
          - `action` 'suppress', required
          - `name` string, required
  - `at` string
  - `cron` string
  - `data` Schema1 (unresolved $ref)
  - `delaySeconds` integer
  - `delivery` object
    - `onOverlap` 'skip' | 'queue'
    - `completion` 'response' | 'callback'
    - `maxDurationSeconds` integer: How long the receiver may take to answer, in seconds
  - `everySeconds` integer
  - `endpoint` string
  - `url` string, uri
  - `latencyClass` 'realtime' | 'bulk'
  - `lateness` object
    - `maxStalenessSeconds` integer
    - `policy` 'skipAhead' | 'catchUp'
  - `partitionKey` string
  - `name` string
  - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
  - `tags` string[]: Up to 16 distinct searchable tags. Omission preserves tags on replacement; [] clears them.
  - `timeZone` string

## Response `200`

Replace a schedule

- object
  - `occurrence` object, required
    - `attemptCount` integer, required
    - `firstAttemptLatenessMs` integer
    - `firstAttemptStartedAt` string
    - `timingEligibility` 'eligible' | 'customer_blocked' | 'platform_blocked'
    - `timingEligibilityReason` string
    - `timingPolicyVersion` string
    - `generation` integer, required
    - `id` string, required
    - `plannedFor` string, required
    - `schedule` string, required
    - `sequence` integer, required
    - `settledAt` string
    - `state` 'planned' | 'due' | 'dispatching' | 'retry_wait' | 'ambiguous' | 'succeeded' | 'terminal_failed' | 'cancelled' | 'skipped_stale', required
  - `schedule` object, required
    - `autoPauseAfterFailures` union: Consecutive failed runs before automatic pause: 1–100 or "never". Defaults to 5 on create; omission on replace preserves the setting. One-shot schedules are unaffected.
      - integer
      - 'never'
    - `consecutiveFailedRuns` integer
    - `autoPauseReason` object, nullable
      - `failedRuns` integer, required
      - `status` integer
      - `diagnostic` string, required
      - `pausedAt` string, required
    - `http` object
      - `method` 'POST' | 'PUT' | 'GET', required
      - `body` union, required
        - object
          - `mode` 'envelope', required
        - object
          - `mode` 'none', required
        - object
          - `mode` 'json', required
          - `value` Schema0 (unresolved $ref)
      - `headers` union[], required
        - union
          - object
            - `name` string, required
            - `secret` false, required
            - `value` string, required
          - object
            - `name` string, required
            - `secret` true, required
            - `configured` true, required
          - object
            - `name` string, required
            - `suppressed` true, required
    - `archivedAt` string
    - `data` Schema1 (unresolved $ref)
    - `createdAt` string, required
    - `delivery` object
      - `completion` 'response' | 'callback', required
      - `maxDurationSeconds` integer, required
      - `onOverlap` 'skip' | 'queue', required
    - `endpoint` string
    - `endpointUrl` string, uri
    - `generation` integer, required
    - `id` string, required
    - `latencyClass` 'realtime' | 'bulk', required
    - `lateness` object, required
      - `maxStalenessSeconds` integer
      - `policy` 'skipAhead' | 'catchUp', required
    - `name` string
    - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
    - `tags` string[]: Up to 16 distinct searchable tags. Omission preserves tags on replacement; [] clears them.
    - `partitionKey` string
    - `nextDueAt` string
    - `recurrence` union, required
      - object
        - `kind` 'at', required
      - object
        - `everySeconds` integer, required
        - `kind` 'every', required
      - object
        - `cron` string, required
        - `kind` 'cron', required
        - `timeZone` unknown, required
    - `status` 'active' | 'paused' | 'cancelled' | 'completed', required
    - `updatedAt` string, required
    - `version` integer, required
  - `endpointSigningSecret` object
    - `guidance` string, required
    - `returned` false, required
    - `revealUrl` string, uri

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `403`: Problem document. Possible codes at this status: scope_missing.
- `404`: Problem document. Possible codes at this status: not_found.
- `409`: Problem document. Possible codes at this status: plan_limit_reached, project_archived, state_conflict, version_conflict.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)