---
title: "Update a schedule"
method: PATCH
path: "/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}"
tags: ["AgentScheduleService", "Agent Schedules"]
---

# Update a schedule

`PATCH /v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}`

Updates a schedule for an agent

## Path parameters

- `workspaceId` string, required
- `agentId` string, required
- `id` string, required

## Request body

- UpdateAgentScheduleRequest — Update agent schedule request.
  - `workspaceId` string — Workspace ID.
  - `agentId` string — Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.
  - `id` string — Schedule ID. Accepts the canonical `as_…` form or the `external_id:<value>` form.
  - `metadata` UpdateResourceMetadata — UpdateResourceMetadata contains the user-provided fields for updating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.
    - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
  - `spec` AgentScheduleSpec — AgentScheduleSpec is the user-provided configuration for a schedule.
    - `schedule` AgentScheduleSpecSchedule, required — Schedule defines WHEN the schedule fires. Temporal-style structured form: a list of calendar rules (wall-clock) and/or interval rules (duration), OR'd together. At least one rule is required.
      - `calendars` ScheduleCalendar[] — Wall-clock rules. May be empty if `intervals` is non-empty.
        - `second` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `minute` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `hour` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `dayOfMonth` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `month` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `dayOfWeek` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `comment` string
      - `intervals` ScheduleInterval[] — Duration-based rules. May be empty if `calendars` is non-empty.
        - `every` string
        - `offset` string — Phase shift within `every`. Must be < `every` (enforced at runtime).
      - `timezone` string — IANA tz name (e.g. "America/New_York"). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone.
    - `overlapPolicy` 'OVERLAP_POLICY_UNSPECIFIED' | 'OVERLAP_POLICY_ALLOW' | 'OVERLAP_POLICY_SKIP', enum — What to do when the previous run is still in flight. Defaults to SKIP.
    - `firstUserMessage` string — Optional explicit first user message passed to CreateObjective on each fire. Becomes the first user message in the objective's chat history. When unset, the fired objective defers to the selected variation's first_user_message_template.
    - `variationId` string — Optional explicit variation. When unset, the agent's variation_selection_mode chooses per fire.
    - `systemPromptData` object — Optional data rendered into the variation's system_prompt_template when each fired objective is created. If the agent has a system_prompt_data_schema, this must satisfy it.
    - `firstUserMessageData` object — Optional data rendered into the variation's first_user_message_template when each fired objective is created. Separate from `system_prompt_data`, which renders the system prompt template.
  - `updateMask` string, field-mask — Fields to update.

## Response `200`

OK

- AgentSchedule — AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.
  - `metadata` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
    - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")
    - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
    - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID)
    - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
    - `profileId` string, required — ID of the actor (user or service account) that created this resource
    - `createdAt` string, date-time, required — Timestamp when this resource was created
    - `updatedAt` string, date-time — Timestamp when this resource was last updated
  - `spec` AgentScheduleSpec, required — AgentScheduleSpec is the user-provided configuration for a schedule.
    - `schedule` AgentScheduleSpecSchedule, required — Schedule defines WHEN the schedule fires. Temporal-style structured form: a list of calendar rules (wall-clock) and/or interval rules (duration), OR'd together. At least one rule is required.
      - `calendars` ScheduleCalendar[] — Wall-clock rules. May be empty if `intervals` is non-empty.
        - `second` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `minute` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `hour` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `dayOfMonth` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `month` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `dayOfWeek` ScheduleRange[]
          - `start` integer
          - `end` integer
          - `step` integer
        - `comment` string
      - `intervals` ScheduleInterval[] — Duration-based rules. May be empty if `calendars` is non-empty.
        - `every` string
        - `offset` string — Phase shift within `every`. Must be < `every` (enforced at runtime).
      - `timezone` string — IANA tz name (e.g. "America/New_York"). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone.
    - `overlapPolicy` 'OVERLAP_POLICY_UNSPECIFIED' | 'OVERLAP_POLICY_ALLOW' | 'OVERLAP_POLICY_SKIP', enum — What to do when the previous run is still in flight. Defaults to SKIP.
    - `firstUserMessage` string — Optional explicit first user message passed to CreateObjective on each fire. Becomes the first user message in the objective's chat history. When unset, the fired objective defers to the selected variation's first_user_message_template.
    - `variationId` string — Optional explicit variation. When unset, the agent's variation_selection_mode chooses per fire.
    - `systemPromptData` object — Optional data rendered into the variation's system_prompt_template when each fired objective is created. If the agent has a system_prompt_data_schema, this must satisfy it.
    - `firstUserMessageData` object — Optional data rendered into the variation's first_user_message_template when each fired objective is created. Separate from `system_prompt_data`, which renders the system prompt template.
  - `info` AgentScheduleInfo — AgentScheduleInfo provides read-only runtime data about a schedule.
    - `nextFireAt` string, date-time — When the schedule will next fire. Computed from the spec; absent when the schedule is STATE_PAUSED/STATE_ARCHIVED or has no future fire times.
    - `lastFireAt` string, date-time — When the schedule last fired (regardless of objective outcome).
    - `lastObjectiveId` string — ID of the most recent objective the schedule created.
    - `lastSkippedAt` string, date-time — When the schedule most recently skipped a fire (SKIP policy + prior in flight).
    - `lastSkipReason` string — Reason for the most recent skip (e.g. "previous objective still running").
    - `totalFires` integer — Lifetime count of objectives created by this schedule.
    - `createdBy` Profile — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
      - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
        - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")
        - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
        - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
        - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
        - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
        - `profileId` string, required
        - `createdAt` string, date-time
      - `spec` ProfileSpec, required — Configuration for a profile.
        - `email` string — Email address of the profile. Required and unique within an account for user profiles.
        - `name` string — Display name (e.g., "Bobby Tables").
        - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal.
  - `state` 'STATE_UNSPECIFIED' | 'STATE_ACTIVE' | 'STATE_PAUSED' | 'STATE_ARCHIVED', enum, required — The current lifecycle state of the schedule. Output only. Schedules are created STATE_ACTIVE; use the :pause, :resume, and :archive actions to transition between states.

## Other responses

- `default` — Default error response

## Changes

- **2026-07-04** `09ccecfe3ece` — 6 warning, 6 info
  - removed the request property `spec/data`
  - removed the request property `spec/initialMessage`
  - removed the request property `spec/userData`
  - removed the optional property `spec/data` from the response with the `200` status
  - …8 more
- **2026-07-02** `06e0e37c1499` — 2 warning, 1 info
  - removed the request property `metadata/bundleKey`
  - removed the optional property `metadata/bundleKey` from the response with the `200` status
  - added the optional property `info/createdBy/metadata/createdAt` to the response with the `200` status
- **2026-06-10** `d2d65c2665bd` — 1 breaking, 3 info
  - the response property `spec/initialMessage` became optional for the status `200`
  - added the new optional request property `spec/userData`
  - the request property `spec/initialMessage` became optional
  - added the optional property `spec/userData` to the response with the `200` status
- **2026-06-09** `13d98d37dd96` — 2 warning, 2 info
  - removed the request property `spec/status`
  - removed the optional property `spec/status` from the response with the `200` status
  - added the optional property `metadata/updatedAt` to the response with the `200` status
  - added the required property `state` to the response with the `200` status
- **2026-06-05** `0702cb021b66` — 1 warning
  - added the new `PROFILE_TYPE_UNSPECIFIED` enum value to the `info/createdBy/spec/type` response property for the response status `200`

[Change history](https://skmtc.dev/cadenya/apis/cadenya-api/changes/v1/workspaces/:workspaceId/agents/:agentId/schedules/:id/patch.md)

---

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