Concepts

Idempotency

A network failure can leave you not knowing whether a write happened. Operations that take an Idempotency-Key let you retry that write with the same key, so the service recognises the retry as the same change.

Which operations take a key

Each operation's spec declares whether it takes the header, and the API reference shows it as a badge:

• Idempotency-Key required — the request is refused without one. The SDK accepts 8 to 128 printable ASCII characters.
• Idempotency-Key optional — send one to make retries safe. The SDK accepts 1 to 256 printable ASCII characters.

Sending a key

curl -X POST "https://os.one.ml/api/v1/gears/runs" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: run-2026-10-20-nightly" \
  -H "Content-Type: application/json" \
  -d '{"workflowId": "…", "workflowVersion": "1", "actorId": "…", "inputRef": "…"}'

await genesis.call('gears_startRun', { body }, {
  headers: { 'Idempotency-Key': 'run-2026-10-20-nightly' },
})

genesis gears runs start --body-file run.json --idempotency-key run-2026-10-20-nightly

{ "name": "gears_startRun", "arguments": { "body": { "…": "…" }, "idempotency_key": "run-2026-10-20-nightly" } }

Choosing keys

• One key per intended change, not per attempt. Generate it before the first attempt and reuse it on every retry of that change.
• Derive it from your own identifiers when you have them (invoice-4821-charge), or use a UUID.
• A new change needs a new key. Never reuse a key for a different change.

Related

• Rate limits · Errors

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support