Idempotency

Network retries can turn one intended mutation into two. The public API supports idempotent retries on every mutating request (POST, PUT, PATCH, DELETE) via the Idempotency-Key header.

Requirements

1. Send the API key as Authorization: Bearer owk_... — idempotency slots are scoped by a hash of the Authorization header, so the X-Api-Key form does not activate them.
2. Generate one key per logical operation (a UUIDv4 is perfect) and reuse that same value for every retry of that operation — not per attempt.

curl -X POST "https://<host>/api/public/v1/..." \
  -H "Authorization: Bearer $ONWORK_API_KEY" \
  -H "Idempotency-Key: 6f1c2c9a-8f0e-4bfa-9a3e-1d2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Semantics

Situation	Result
First request with a key	Executes normally; the response is recorded.
Retry after completion	The stored response is replayed verbatim, with header Idempotent-Replay: true. No side effect runs twice.
Retry while the first is still in flight	409 conflict — wait briefly and retry with the same key.
Server error (5xx) on the first request	Nothing is recorded — the retry executes normally.

Stored responses are kept for 24 hours; after that a reused key executes as a fresh request.

When to use it

Today the public API surface is read-only, so idempotency is not yet load-bearing — but wire it into your client now: every future write endpoint supports it out of the box.