What signals update Actually Lets You Change, Per Type

Learn which settings genuinely persist through signals update for a given signal type, and the two-part rule for what happens when you pass a field outside that type's editable shape: rejected alone, silently dropped when accompanied by a valid key.

What you will build

Two update attempts against the same Promotion signal's lookBackTimeWindowInMonths, one alone, one combined with a valid key, showing the different outcome of each.

clay signals update <id> --input '{"lookBackTimeWindowInMonths":6}'
    ↓ validation_error: "--input: names nothing this signal's type can change"

clay signals update <id> --input '{"segmentIds":[...],"lookBackTimeWindowInMonths":6}'
    ↓ exit 0, but lookBackTimeWindowInMonths is silently unchanged

AI Prompt

Using the Clay CLI, determine what signals update actually persists for a
given type, versus what's rejected or silently dropped.

Requirements:
- Each signal type's editable `--input` shape for `signals update` is
  narrower than its creation shape. For Promotion (and JobChange), the
  documented editable shape is `{"segmentIds": [...]}` only.
  lookBackTimeWindowInMonths, despite being a real, meaningful field shown
  in `signals get`'s output, is not part of it.
- The two-part rule: passing only an out-of-shape key
  (e.g. `{"lookBackTimeWindowInMonths":6}` alone, nothing else) is rejected
  with a validation_error naming exactly what the type accepts (e.g. "a
  Promotion signal accepts segmentIds"). Passing that same out-of-shape
  key alongside a valid one (e.g. `{"segmentIds":[...],
  "lookBackTimeWindowInMonths":6}`) succeeds with exit 0, and the
  out-of-shape key is silently dropped, not applied, with no error and no
  warning in the response.
- Practical implication: an update that only touches an editable field
  never reveals this distinction. It only surfaces if you pass an
  out-of-shape key in isolation (real error) versus bundled with a real
  change (silent no-op). Always re-`get` after an update to confirm what
  actually changed, rather than trusting the update call's exit code alone.
- Run the verification step below before finishing.

Prerequisites

• The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
• An existing Promotion or JobChange signal

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Confirm the creation-time value

clay signals get td_0tlqbq5TV8dpkDpmYBi | jq '.signal.inputs.lookBackTimeWindowInMonths'

Real output:

3

2. Pass the out-of-shape key alone: a real error

clay signals update td_0tlqbq5TV8dpkDpmYBi --input '{"lookBackTimeWindowInMonths":6}'

Real output:

{"error": {"code": "validation_error", "message": "--input: names nothing this signal's type can change — a Promotion signal accepts segmentIds"}}

3. Pass the same key alongside a valid one: silently dropped

clay signals update td_0tlqbq5TV8dpkDpmYBi --input '{"segmentIds":["audseg_0tjs3u3yAgacWPpe926"],"lookBackTimeWindowInMonths":6}'

Real output: exit 0, full signal object returned, no error of any kind:

{"id": "td_0tlqbq5TV8dpkDpmYBi", "signal": {"inputs": {"lookBackTimeWindowInMonths": 3, "segmentIds": ["audseg_0tjs3u3yAgacWPpe926"]}}}

4. Confirm the real value never changed

clay signals get td_0tlqbq5TV8dpkDpmYBi | jq '.signal.inputs.lookBackTimeWindowInMonths'

Real output: still 3, after the update in step 3:

3

Verify the result

Confirm the behavior above holds by re-running the key commands and checking the result:

clay signals update <id> --input '{"lookBackTimeWindowInMonths":6}'
clay signals update <id> --input '{"segmentIds":[...],"lookBackTimeWindowInMonths":6}'

Expected: the first call (out-of-shape key alone) is rejected with a validation_error naming what the type actually accepts; the second call (same key alongside a valid one) succeeds with exit 0, and a subsequent signals get shows the out-of-shape field's value is unchanged from before either call.

How it works

The validation check looks at whether anything meaningful was requested. A lone out-of-shape key means the whole call has nothing valid to apply, which is treated as a malformed request and rejected outright. Once at least one editable key is present, the call has real work to do, and any additional out-of-shape keys are simply excluded from what gets applied rather than failing the whole call. As a result, the exact same out-of-shape field produces two different outcomes depending on what else is in the same --input object, which matters for anyone scripting updates from a template that might carry stale or extra keys.

Common issues

Assuming an out-of-shape key always errors, based on testing it alone

Testing {"lookBackTimeWindowInMonths":6} by itself produces a clean validation_error. That error only fires when nothing else valid is present in the same --input. Bundle it with a real change (like segmentIds) and it's silently dropped instead. Test both shapes, and re-get after any update where you're not certain every key is editable.

Trusting an update's exit code as proof every field applied

Most commands in this CLI that accept an input successfully also apply all of it, which makes exit 0 an intuitive stand-in for success. A bundled update can succeed while quietly leaving one of its fields untouched. Re-read the resource after any update that includes a field you're not certain is in the type's editable shape.

Next steps

• Read each type's editable-shape documentation in clay signals update --help before scripting an update, rather than assuming creation-time fields are also update-time fields.
• If a lookback window or identifier truly needs to change, create a new signal rather than trying to update the old one.

verification:
  status: verified
  tested_at: "2026-09-21"
  product_version: "clay CLI 1.2.0"
  command: "clay signals update td_0tlqbq5TV8dpkDpmYBi --input '{\"lookBackTimeWindowInMonths\":6}' ; clay signals update td_0tlqbq5TV8dpkDpmYBi --input '{\"segmentIds\":[\"audseg_0tjs3u3yAgacWPpe926\"],\"lookBackTimeWindowInMonths\":6}' ; clay signals get td_0tlqbq5TV8dpkDpmYBi"
  expected_result: "The lone-key update is rejected with a validation_error naming the type's real editable shape; the bundled update succeeds with exit 0; a fresh get shows lookBackTimeWindowInMonths is still 3 in both cases, never applied either way, but only the lone attempt errors."