# Workflow: Create and Iterate on a Timer Draft

Use this workflow when a user wants to create a countdown timer through a conversation. The draft can be edited repeatedly until it is saved. Treat `POST /v2/timer-frames/{timerFrameId}/save` as the final commit step, not as a normal edit operation.

## Required context

- Base URL: `https://dev.niftyimages.com/v2`
- Auth: `Authorization: Bearer $NIFTYIMAGES_API_KEY`
- Optional font lookup: `GET /v2/fonts`

## Before live calls

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

## Sequence

1. Create a Timer Frame draft with `POST /v2/timer-frames`.
2. Preserve `conversationId`, `timerFrameId`, `expiresUtc`, `preview.url`, and `saveReady`.
3. After every user edit, call `PATCH /v2/timer-frames/{timerFrameId}` with the same `conversationId`.
4. Show or return the latest `preview.url`.
5. Continue iterating until the user says the preview is final.
6. Summarize the current timer name, target date/time, timezone, visual choices, and preview URL.
7. Ask for explicit confirmation before saving.
8. Save with `POST /v2/timer-frames/{timerFrameId}/save`.
9. Stop editing the Timer Frame draft and return the live saved image/deployment details.

## Save is final

`/save` turns the temporary Timer Frame draft into a live timer image that can be used in an email campaign or website. Make it the last Timer Frame draft call in the conversation.

Do not call `/save` simply because `saveReady` is true. `saveReady` only means the draft is valid enough to save; it does not mean the user approved the design.

Before saving, ask a confirmation such as:

```text
The current preview is ready to save as "July launch countdown" for July 4, 2026 at 12:00 PM America/New_York. Once I save it, this draft is locked in and the timer will be live for use in campaigns or websites. Save it now?
```

## Create

```bash
curl https://dev.niftyimages.com/v2/timer-frames \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_july-campaign",
    "targetDateUtc": "2026-07-04T16:00:00Z",
    "timeZoneId": "America/New_York",
    "width": 600,
    "height": 140,
    "backgroundColor": "#0A2540",
    "numberColor": "#FFFFFF",
    "showLabels": true
  }'
```

## Update

```bash
curl -X PATCH https://dev.niftyimages.com/v2/timer-frames/{timerFrameId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_july-campaign",
    "numberBackplate": "pie",
    "numberFontSizeDelta": 8,
    "showLabels": false
  }'
```

## Save

Call this only after final user confirmation.

```bash
curl -X POST https://dev.niftyimages.com/v2/timer-frames/{timerFrameId}/save \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_july-campaign",
    "name": "July launch countdown"
  }'
```

## Agent notes

- If a user says "start over", create with `startOver: true` and the same `conversationId`.
- Keep the last known good draft if an update fails.
- Ask the user before saving if `saveReady` is false or validation returned errors.
- Use `numberBackplate` values such as `none`, `pie`, `ticks`, `segmented`, or `ring` rather than inventing unsupported visual modes.
- Ask the user before saving even when `saveReady` is true.
- After a successful save, do not continue patching the draft. Return the saved image/deployment details and explain that the timer is live.