---
title: "Update metadata on an existing scheduled job: enabled, kill switch, expires_at, params, schedule, and timezone."
method: PATCH
path: "/v1/jobs/{id}"
tags: ["jobs"]
---

# Update metadata on an existing scheduled job: enabled, kill switch, expires_at, params, schedule, and timezone.

`PATCH /v1/jobs/{id}`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/jobs/{id}`
- Auth: HTTP bearer

Update metadata on an existing scheduled job: enabled, kill switch, expires_at, params, schedule, and timezone. Package-owned jobs keep source in the package repo, so name, code, and published source cannot change here — edit the package and publish. Recurring schedules belong on a package (`kody.jobs`); deferred one-shots use `workflows.create`.

Org permission: `job:write`.

## Path parameters

- `id` string, required: Existing job id from jobList or jobGet output.

## Request body

- object
  - `name` unknown
  - `params` object, nullable: Optional replacement params object passed as the first argument to the job entrypoint. Pass null to clear existing params.
  - `schedule` union: Optional replacement schedule for the job.
    - object
      - `type` 'once', required
      - `run_at` string, required: UTC timestamp for the one-off run, for example 2026-04-20T18:30:00Z.
    - object
      - `type` 'interval', required
      - `every` string, required: Recurring interval such as 15m, 1h, or 1d using ms, s, m, h, or d units.
    - object
      - `type` 'cron', required
      - `expression` string, required: Standard 5-field cron expression: minute hour day-of-month month day-of-week.
  - `timezone` string, nullable: Optional timezone label for cron display and schedule calculation. Pass null to reset to UTC.
  - `enabled` boolean: Enable or disable the job without deleting it.
  - `kill_switch_enabled` boolean: Force the job off regardless of schedule. This remains visible in jobList and jobGet for debugging.
  - `expires_at` string, nullable: Optional UTC ISO timestamp after which the platform stops scheduling this job and auto-disables it (enabled=false). Pass null to clear.
  - `code` unknown

## Response `200`

Success.

- object
  - `job_id` string, required
  - `name` string, required
  - `source_id` string, required
  - `published_commit` string, nullable, required
  - `storage_id` string, required
  - `params` object
  - `schedule` union, required
    - object
      - `type` 'once', required
      - `run_at` string, required: UTC timestamp for the one-off run, for example 2026-04-20T18:30:00Z.
    - object
      - `type` 'interval', required
      - `every` string, required: Recurring interval such as 15m, 1h, or 1d using ms, s, m, h, or d units.
    - object
      - `type` 'cron', required
      - `expression` string, required: Standard 5-field cron expression: minute hour day-of-month month day-of-week.
  - `schedule_summary` string, required
  - `timezone` string, required
  - `enabled` boolean, required
  - `kill_switch_enabled` boolean, required
  - `expires_at` string, nullable, required
  - `expired` boolean, required
  - `created_at` string, required
  - `updated_at` string, required
  - `last_run_at` string
  - `last_run_status` 'success' | 'error'
  - `last_run_error` string
  - `last_duration_ms` integer
  - `next_run_at` string, required
  - `run_count` integer, required
  - `success_count` integer, required
  - `error_count` integer, required
  - `run_history` object[], required
    - `id` string: Run record id for drill-down with runGet when available.
    - `started_at` string, required
    - `finished_at` string, required
    - `status` 'success' | 'error', required
    - `duration_ms` integer, required
    - `error` string
  - `enablement_hint` string, nullable, required: When the job is enabled but has no on enablement (or only paused ones), an agent-directed message that includes the exact enablementEnable call. Null when the job is off or already has an on enablement.

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

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