Retry a timed-out Sume Agent Completion without a second run

To retry a timed-out POST /v1/agent/completions without starting a second run, send the same Idempotency-Key with the same payload. Sume returns the original receipt with idempotency_hit: true. If you reuse the key with a different payload, the API returns 409 idempotency_conflict.

Why a retry is dangerous without a key

An Agent Completion is asynchronous. The create call returns 202 and a receipt, and the run continues on its own. If your HTTP client times out waiting for that 202, you do not know whether the run exists. Resending without a key can start a second run, and each run can spend generation budget up to the generation_spend_cap_usd you sent.

The request

This is a minimal call with the required cap. generation_spend_cap_usd has no default, and the request fails with 400 invalid_request if it is missing.

curl -sS -X POST "https://api.sume.com/v1/agent/completions" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: weekly-teaser-2026-w41" \
  -d '{
        "instruction": "Draft a 15-second teaser script for the Aurora headphones.",
        "generation_spend_cap_usd": 2
      }'
# Run the same command again with the same key and body: same receipt,
# idempotency_hit true. Change the body and reuse the key: 409.

What counts as the same request

The points that matter here, in the order you will hit them:

Choosing a key

Derive the key from the business event, not from the clock. A key built from a timestamp changes on every attempt and defeats the point. A key built from "weekly-teaser-2026-w41" is stable across retries and changes next week. Keys are 1 to 255 characters.

This matters more with fast, cheap planning models, because teams then run more completions per hour and a duplicate becomes harder to spot in the logs. Claude Haiku 5.5, released 2026-10-07 per Anthropic's page, is one such model, though the Agent Completions model field accepts only sume-agent.

After the retry

Poll status_url from the receipt until next_action is no longer poll_status, or register a communication.webhook_url. Either way, the receipt id is the same, so your downstream code can dedupe on it.

What to store

Store three values at submit time: your idempotency key, the receipt id (it begins agrun_), and the thread_id. Each completion runs in a new thread, and the docs say you cannot continue a prior thread with thread_id at this time. If the create call times out and you never saw the receipt, retry with the key and you will receive it. Then keep polling the same receipt rather than creating anything new.

Do not put the key in the prompt. The Idempotency-Key is an HTTP header, and the docs describe it as working the same way as on Action runs. A key that only lives in your instruction text does nothing for the API. Also keep the key stable only for exact retries. If you intentionally want a second, different run for the same event, such as a re-render after a failed review, give it a new key so the API does not hand you the first receipt.