Update timer

Scope and access

User-scoped timers are private to the authenticated user.
Team-scoped timers can only be listed or managed by a team owner.
Repo-scoped timers can be listed and fetched by users with repo read access; creating, updating, or deleting one requires maintainer access.
A timer UUID is only reachable through its owning user, team, or repo scope.

Endpoints

PUT /api/v1/users/{username}/timers/{timer_uuid}
PUT /api/v1/teams/{team_slug}/timers/{timer_uuid}
PUT /api/v1/teams/{team_slug}/repos/{repo_slug}/timers/{timer_uuid}
PUT /api/v1/users/{username}/repos/{repo_slug}/timers/{timer_uuid}

Authenticated

Schedule fields

JSON / MCP	CLI	Behavior
`run_in`	`--run-in`	Fire once after a duration such as `5m` or `2h`.
`run_at`	`--run-at`	Fire once at a future RFC 3339 instant.
`every_seconds`	`--every-seconds`	Repeat on a fixed interval of at least one second.
`time_of_day`	`--time-of-day`	Repeat at a local `HH:MM` time.
`days_of_week`	`--days-of-week`	Required with `time_of_day`. Use `all` for every day, or provide a non-empty selection of three-letter names: Sun, Mon, Tue, Wed, Thu, Fri, Sat.
`timezone`	`--timezone`	IANA timezone for `time_of_day`; defaults to `UTC`.

Omit all schedule fields to preserve the current schedule. When replacing it, provide exactly one of run_in, run_at, every_seconds, or time_of_day. API and MCP callers may omit schedule_kind and let the server infer once or interval; the CLI always infers it from the schedule flag.

Request

Omitted fields are preserved. Allowed requested statuses are active, paused, and cancelled; completed is set by the scheduler after a one-off fires.

{
  "message": "Review the updated release checklist",
  "status": "paused"
}

If any schedule field is supplied, it replaces the whole schedule:

{
  "run_in": "2h",
  "status": "active"
}

Reactivating a completed or cancelled timer requires a new schedule so it has a future run.

Success

200 OK with the updated timer JSON.

Timer response

{
  "uuid": "8f7a2ba9-8a67-4a56-a8e8-0fe9f26717f6",
  "message": "Review the release checklist",
  "scope": "user",
  "schedule_kind": "interval",
  "schedule": "Mon, Tue, Wed, Thu, Fri at 09:00 (America/New_York)",
  "run_at": null,
  "every_seconds": null,
  "time_of_day": "09:00",
  "days_of_week": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "timezone": "America/New_York",
  "status": "active",
  "next_run_at": "2026-08-24T13:00:00Z",
  "last_run_at": null,
  "run_count": 0,
  "created_at": "2026-08-22T22:00:00Z"
}