Idempotency
Networks fail after the server has done the work: the upload landed, but the response never reached you. Send an Idempotency-Key header on an upload and you can retry the exact same request without storing, counting, or billing a second copy. The retry returns the original asset.
Idempotency keys are supported on uploads that create media: POST /v1/images, POST /v1/videos, POST /v1/videos/uploads (resumable video), and POST /v1/audio. They need a key-authenticated request: keyless image uploads validate the header's format but ignore it, and batch uploads don't accept it (a batch is already idempotent per collection type + name).
Send a key
A key is 1–255 printable ASCII characters with no spaces (a malformed key is 400 validation_error). Use something derived from the work you're doing (release-notes-hero-v1, a job id, a UUID you persist before the first attempt), and send the same value on every retry.
curl -X POST https://api.pixelvault.dev/v1/images \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Idempotency-Key: release-notes-hero-v1" \
-F "file=@hero.png" What a retry returns
| Situation | Response |
|---|---|
| First request with this key | The normal success response (201) |
| Same key, same inputs, original succeeded | 200 with the stored asset and "replayed": true |
| Same key, different inputs | 422 idempotency_key_reuse |
| Video/audio: same key while the first request is still uploading | 409 idempotency_in_progress (the error carries upload_id, asset_id, expires_at); retry later |
| Video/audio: the asset created with this key was deleted | 410 idempotency_result_deleted |
A replay describes the asset as it was stored, not the parameters of the retry. Fields applied only to new assets (custom metadata, describe=true) are ignored on a replay: change metadata later with PATCH.
{
"data": {
"id": "img_abc123",
"url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
"replayed": true
}
} Conflicts: 422 idempotency_key_reuse
Reusing a key with different inputs returns 422 idempotency_key_reuse on images, videos and audio alike. That refusal is deliberate: returning a URL for the wrong asset would be worse than failing. Use a new key for a new upload.
HTTP/1.1 422 Unprocessable Content
{
"error": {
"code": "idempotency_key_reuse",
"message": "This Idempotency-Key was already used with different video inputs."
}
} What counts as "different" depends on the media type:
| Images | Video and audio | |
|---|---|---|
| Compared inputs | Image bytes and visibility; also refused once a temporary image has passed its expires_in | Source (bytes or URL), filename, size, visibility, social-ready flag, TTL, folder, collection, metadata |
| Key retention | As long as the image exists | 24 hours: an unfinished upload session expires 24 hours after it starts, and a completed upload's replay marker is kept 24 hours after completion |
| Checksum header | None: the server hashes the bytes | Direct byte uploads with a key must send X-PixelVault-Content-SHA256 (64 hex chars). Missing: 400 idempotency_checksum_required; bytes don't match: 400 checksum_mismatch. URL imports need no checksum. |
| Concurrent duplicates | Both run; the loser returns the winner's image as a replay | 409 idempotency_in_progress until the first finishes |
Video and audio checksums
For direct byte uploads, compute the SHA-256 of the file once and send it with the key. PixelVault verifies it while streaming, so a corrupted retry can never be mistaken for the original:
SHA256=$(shasum -a 256 launch-demo.mp4 | awk '{print $1}')
curl -X POST https://api.pixelvault.dev/v1/videos \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: video/mp4" \
-H "Content-Length: $(wc -c < launch-demo.mp4)" \
-H "X-PixelVault-Filename: launch-demo.mp4" \
-H "X-PixelVault-Content-SHA256: $SHA256" \
-H "Idempotency-Key: release-demo-v1" \
--data-binary @launch-demo.mp4 Resumable video uploads take the whole-file sha256 in the POST /v1/videos/uploads body instead of the header. Re-initiating an active session with the same key returns 200 with the same upload_id and replayed: true, so you can resume; once completed it returns the committed asset. Each part of a keyed session needs X-PixelVault-Part-SHA256 (400 part_checksum_required otherwise); re-sending a stored part with the same bytes returns replayed: true, different bytes return 409 part_already_uploaded. POST …/complete is naturally replayable after a lost success response. See the large-file walkthrough.
Idempotency is not deduplication
An idempotency key makes one logical request retry-safe; different keys always create distinct assets, and content is never deduplicated across owners or privacy boundaries. For images only, dedupe=true is the content-reuse option: an existing image with identical bytes, visibility, folder and at least the lifetime you ask for is returned (200, "deduplicated": true) and nothing is stored or counted. Dedup is best-effort (simultaneous uploads of the same bytes can each be stored), and dedupe cannot be combined with Idempotency-Key (400 validation_error). Video and audio have no dedupe option.
Next steps
- Error reference for
idempotency_key_reuse. - Upload video with checksums and resumable sessions.
- Why retry-safe uploads matter for agents.