API-triggered scheduled run: key per week, not $(uuidgen)

For a weekly API-triggered Sume run, build the Idempotency-Key from the thing that makes the run unique, such as the schedule id and the ISO week, and not from $(uuidgen). The invoke example in the docs uses uuidgen because a one-off command needs some value. A fresh key on every call means a retry after a timeout is a new request, and a new request is a new run. A key like aut_weekly-teaser-2026-W41 sent twice returns the original receipt with idempotency_hit: true.

The invoke call

A run needs the schedule's status to be active, api_trigger_enabled to be true, and an API key with actions:read and actions:write. Keys created before the API-call trigger shipped lack those scopes and fail with 403 insufficient_scope; scopes cannot be added to an existing key. The body accepts input, on_active_run, generation_spend_cap_usd, primary_output_key, output_schema, response_format and communication. Unknown top-level properties are silently dropped, not rejected.

curl -sS -X POST "https://api.sume.com/v1/actions/$ACTION_ID/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

Where the key should come from

Replace the $(uuidgen) header with a value that is identical on every retry of the same logical trigger. The table shows what changes and what must not.

What happens on a replay

If you send a key again with the same operation, the API returns the original receipt with idempotency_hit: true. If the key is reused with a different payload, the API returns 409 idempotency_conflict. So when you change input for a re-run on purpose, change the key too, for example by adding a suffix for the revision.

The overlap setting is separate. on_active_run defaults to skip for Action runs, which means a trigger that arrives while a run is active is skipped. Format runs default to allow. Idempotency answers the question of whether this is the same request; on_active_run answers whether a run is already going.

Spend and status

Set generation_spend_cap_usd on the call if you want a number below the Action's own cap: the API clamps to min(request, Action cap), and a request cannot raise the cap. null removes the automation ceiling, though the wallet balance and admission limits still apply, and 0 is rejected with 400. Poll status_url from the 202 receipt until next_action is no longer poll_status.

A worked key scheme

Name the key from the Action id and the period it belongs to. For a weekly job, use the year and ISO week, as in <action_id>-2026-W41. For a daily one, use the date. For a one-off backfill, use the batch label plus the item number. Keep the key under your control: store the string you sent, so a support question can match it to a receipt.

If you change the input for the same period on purpose, add a revision suffix to the key. Otherwise you will get 409 idempotency_conflict and no run. If the Action is inactive or has the API trigger disabled, the call fails with 409 before any key matters.

A key-less request has no replay protection, so every request starts a new run.

• Weekly: Action id plus ISO week.
• Daily: Action id plus date.
• Revised input: add a suffix.
• No key: every call is a new run.