​
Overview

Network timeouts leave you guessing: did the upload land, or not? Retrying is safe only if the API can recognise the retry. Every write endpoint accepts an optional Idempotency-Key request header for exactly that. The first request with a given key does the work and its response is stored for 24 hours. A retry with the same key and the same body replays that stored response instead of doing the work again, and carries the header Idempotent-Replayed: true.
The header is optional on every v1 endpoint. Existing integrations keep working unchanged — omit it and requests behave exactly as before.
A small number of newer v2 endpoints make the header required instead — see Required on some v2 endpoints below. Omitting it there is a 400, not “no idempotency handling.”

​
Using it

Examples use the default base URL, https://api.orion.file.ai/prod/v1. If your workspace is on an instance-specific host, swap the hostname and change nothing else — see Switching between instances.
1

Generate a key per logical operation

Any opaque string up to 255 characters. A UUIDv4 is recommended. Reuse the same key for every retry of the same operation, and a fresh key for a new operation.
2

Send it as a request header

3

Retry with the same key on failure

On a timeout, 429, or 5xx, retry with the identical key and body. If the original request had already succeeded, you get its response back with Idempotent-Replayed: true and nothing is created twice.

​
Outcomes

“Same body” is determined by a fingerprint over the method, path, workspace, and a canonical form of the request body — key ordering and whitespace do not matter, so you can resend a re-serialized body safely.

​
Cached failures

A terminal failure is cached and replayed too — a 403, 404, or business 409/422 will not be re-executed under the same key. Two classes are deliberately not cached, so a retry gets a fresh attempt:
  • Transient statuses (408, 425, 429) — a later retry may legitimately succeed.
  • VALIDATION_FAILED and BAD_REQUEST — a corrected body has a different fingerprint and must not be locked out for 24 hours.

​
Endpoints

Idempotency-Key is honoured on every write endpoint:

Files

POST /files/upload · POST /files/upload/multipart · POST /files/upload/multipart/complete · DELETE /files · PATCH /files/{fileId}

Schemas & values

PATCH /files/schema · PATCH /files/{fileId}/values · PATCH /files/schema/rerun · PATCH /schemas · POST /files/schema/export · POST /files/schema/import

File types

PATCH /file-type/approve · PATCH /file-type/rename

Workspace

POST /directories · PATCH /project/setting

Agent (v2)

DELETE /v2/agent/sessions/{session_id} — optional, standard replay. See below for the three agent endpoints where the header is required.

​
Required on some v2 endpoints

Three agent session endpoints require Idempotency-Key rather than treating it as optional — every v2 endpoint added since this became the default for new endpoints follows the same rule: Everything else about the mechanism — the 24h window, “same body” fingerprint, Idempotent-Replayed, and cached-failure rules — is identical to the optional case above.

​
Accepted but ignored

Three POST endpoints are semantically reads. They accept the header for client uniformity but never replay: every call executes fresh, with no 24h window, no Idempotent-Replayed header, and no key-reuse 422.
Idempotency fails open. If the backing store is briefly unreachable the request still proceeds, but non-idempotently — it is a resilience aid, not a transactional guarantee. Keep your own retry bookkeeping for operations where a duplicate would be costly.