Idempotency-Key

Pour toute écriture (POST / PUT / PATCH / DELETE), l'API accepte un header Idempotency-Key: <uuid|opaque-string>.

curl -X POST https://api.superfasttt.ai/api/v1/documents/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 4f8b9e0c-1234-4abc-9def-0123456789ab" \
  -F "file=@./doc.pdf" \
  -F "memory_id=<KB_ID>"

Garanties (replay-safe, en vigueur)

• Le premier appel exécute l'opération normalement. La réponse (status, headers, body) est stockée pendant 24 heures, isolée par bearer token.
• Tout appel suivant qui réutilise la même Idempotency-Key avec le même body renvoie la réponse stockée à l'identique, sans réexécuter l'opération. La réponse rejouée porte le header Idempotent-Replayed: true.
• Une réutilisation de la clé avec un body différent renvoie 409 Conflict avec {"detail": "Idempotency-Key already used with a different request body. Use a fresh key for new operations."}.
• Les réponses non-2xx ne sont pas conservées pour rejeu : un échec transitoire peut être réessayé librement.
• La réponse rejouée est isolée par le header Authorization : un autre jeton ou une autre clé API avec la même clé d'idempotence ne peut jamais voir la réponse rejouée.

Conseil

Générez un UUID v4 par opération métier ; ne réutilisez pas une clé pour deux opérations différentes — ça déclenche le 409.

Limites

• La clé doit faire entre 1 et 255 caractères.
• Les requêtes dont le body dépasse 5 Mo (uploads) sont laissées passer sans conservation pour rejeu — l'opération s'exécute mais sans garantie de replay.
• Les réponses streamées (text/event-stream) ne sont pas conservées pour rejeu.