---
name: timer-target-date
description: Update the target date of an existing saved NiftyImages canvas_timer image. Use when a user wants to reschedule, change, move, or correct the countdown date/time for a live canvas timer, including local date strings like 7/4/2026, explicit time zones, or ISO UTC dates. Do not use for deprecated classic_timer images.
---

# Timer Target Date

Use this skill to update only the target date on a saved `canvas_timer` image.

## API Context

- Base URL: `https://dev.niftyimages.com/v2`
- OpenAPI: `https://dev.niftyimages.com/openapi/v1.json`
- Guide: `https://dev.niftyimages.com/docs/timers.md`
- Auth: `Authorization: Bearer {apiKey}`

## Credential Rules

- If the user wants live API calls and no NiftyImages API key is available, ask for one before calling `/v2`.
- If the user only wants planning or code generation, continue without an API key.
- Never invent, guess, log, or expose the API key.

## Workflow

1. Identify the saved canvas timer image id. If missing, list candidates with `GET /v2/images?type=canvas_timer&q={name}` or ask the user.
2. Capture the desired target date/time exactly from the user.
3. Include `timeZoneId` only when the user supplies one or wants to change the timer timezone.
4. Call `PATCH /v2/timers/{id}/target-date`.
5. Return `targetDateUtc`, `timeZoneId`, `localTargetDate`, and `localTargetTime` to confirm what was saved.

## Date Rules

- Send `targetDate` as a string.
- ISO 8601 values with `Z` or an offset are absolute instants.
- Local date/time values use the supplied `timeZoneId`.
- If `timeZoneId` is omitted for a local date/time, the API uses the timer's existing timezone.
- Date-only values default to midnight in the selected timezone.

## Example

```http
PATCH /v2/timers/418344/target-date
Authorization: Bearer {apiKey}
Content-Type: application/json

{
  "targetDate": "7/4/2026"
}
```

## Do Not

- Do not use this for temporary TimerFrame drafts. Use `PATCH /v2/timer-frames/{timerFrameId}` before a timer is saved.
- Do not use this for deprecated `classic_timer` images.
- Do not convert local date/time to UTC yourself unless the user explicitly supplied an absolute instant. Let the API apply the saved or supplied timezone.
- Do not change visual timer settings with this endpoint.