Idempotency

A network error does not tell you whether the server acted. Retrying a POST blindly risks doing the work twice — a second collection created, a second photo added. Send an Idempotency-Key and the retry is free: Pexafy replays the first response instead of running the request again. This applies to POST requests only. GET and DELETE are already safe to repeat, so they ignore the header.

Using it

Generate a unique key per logical operation — a UUID is the usual choice — and send it with the request:

curl -X POST "https://api.pexafy.com/api/v1/collections" \
  -H "x-api-key: $PEXAFY_API_KEY" \
  -H "Idempotency-Key: 7d1f0c2e-3b64-4f8a-9c11-2ad5e6f80b93" \
  -H "Content-Type: application/json" \
  -d '{"name": "Autumn campaign"}'

Retry the exact same call and you get the same body and the same status code back, plus a header telling you it was a replay rather than a fresh action:

X-Idempotent-Replay: true

Rules

Rule	Detail
Scope	`POST` only. Other methods ignore the header.
Key format	Up to 128 characters, letters, digits, `-` and `_`. Anything else is rejected with `400 INVALID_IDEMPOTENCY_KEY`.
Retention	24 hours. After that the key is forgotten and the same request would act again.
What is stored	Successful responses only (`2xx`). A failed request is not remembered, so you can retry it and actually get through.
Reuse	A key identifies one operation. Reusing it for a different request returns the first response, not the new one — so never reuse a key across operations.

Keys are stored per key value, not per endpoint. Generate a fresh one for each operation you want to be able to retry.

When to bother

Use it whenever a failed call would be expensive to repeat — creating a collection, adding photos in bulk from a job that may be retried by your queue. For plain searches it adds nothing: GET /search/photos is already safe to repeat as often as you like.

Getting Started

AI Assistants (MCP)

Search

Photos

Facets

Collections

Usage

Using it

Rules

When to bother

​Using it

​Rules

​When to bother

Using it

Rules

When to bother