DevelopersYour tokens
Guide

Idempotency

A change sent twice is made once. A client that lost the answer sends the same call again with the same key and gets the same answer back.

Why

A phone loses the connection between sending POST /reminders and hearing back. Was the reminder made? Without a key the only safe answer is to look, and the only easy answer is to send it again and risk two. With a key, send it again: Thaw remembers the first answer and replays it.

How

Put any string of your choosing, up to 200 characters, in the Idempotency-Key header of a change. A UUID is the usual choice.

curl -X POST "https://api.thawed.app/v1/reminders" \
  -H "Authorization: Bearer $THAW_TOKEN" \
  -H "Idempotency-Key: 8c2b1e4a-5f6d-4a7b-9c8d-1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{"title":"Renew the passports","on":"2026-10-01"}'

The first call is made and its answer kept for a day. Every later call with the same key, to the same method and path, from the same token, gets the kept answer back with the same status and the header Idempotent-Replayed: true. Nothing runs a second time.

The rules

  • The key is yours and scoped to you. It is remembered per token (or connection), method and path, so two people can use the same key without meeting, and the same key on POST /reminders and POST /documents/{id}/reviewed are two keys. Nothing of the key itself is stored; a hash of it is.
  • The same key with a different body is a mistake, and is refused with 422 rather than answered with the first call’s result. A body is the JSON sent, or for a multipart request the files by name and size.
  • The same key while the first call is still running is 409. A change holds its key for up to thirty seconds while it runs; try again after a moment and the kept answer is there.
  • A day. After twenty-four hours the key is forgotten and the same call is a new one.
  • Reads pass through. A key on a GET is ignored. A change with no key is made every time it is sent, as it always was.

Which calls take one

Every change that could be made twice by accident carries the chip “Takes Idempotency-Key” in the reference: putting a document in, saving a note, making a reminder, acting on a Checkup item, filing a document as something else, linking a person, sharing by link, and the rest. A change that is the same however often it is sent - revoking a link, marking a document looked at - takes none, because a second one does no harm. Neither do the uploads in parts (each part is its own PUT, and completing twice is a 409 from storage), Ask or the drafts.