Idempotency

Networks fail. If a POST /cases times out, you can’t tell whether Thea created the case. An idempotency key lets you retry without creating it twice.

Send a unique value in the Idempotency-Key header of any POST that creates or changes something (every POST except webhook test events):

curl -X POST "$THEA_API/cases" \
  -H "Authorization: Bearer $THEA_PARTNER_KEY" \
  -H "Thea-Practice-Key: $THEA_PRACTICE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f8e7a52-3c1d-4b9e-9a61-2d5c8f4b7e10" \
  -d '{ … }'

How it works

The first request with a key runs normally. If it succeeds, Thea stores its status code and body for 24 hours.
A retry with the same key and the same body returns the stored response without running the operation again. It includes the header Idempotent-Replayed: true.
A request with the same key but a different body fails with 409 idempotency-key-reused.
Keys are scoped to your partner key and practice, so they can’t collide with other partners’ or other practices’.
Only successful (2xx) responses are stored. Errors aren’t, so you can fix the request (or reopen a closed case) and resend it with the same key.

Choosing keys

Generate a new UUID (v4) for each distinct operation, and reuse it only to retry that operation. A good pattern is to derive it from your own record, such as your referral ID when you create a case, so a crashed worker that restarts uses the same key.

GET and DELETE requests are naturally idempotent and ignore the header.