Expiry & retention
Media you upload with an API key is permanent until you delete it, unless you ask for it to expire. This page covers every way an asset or a link to it can stop working.
| Mechanism | What ends | When |
|---|---|---|
expires_in | The asset and all its derivatives are deleted | After the TTL, at the next hourly sweep (up to about 2 hours late) |
| Keyless upload | The anonymous image | 30 days after upload |
sign_expires_in / expires | One signed link; the asset stays | Exactly at expires |
| Delete endpoint | The asset, its derivatives, and every link | Immediately |
Closing a ci_build collection | Its members | At the next sweep |
| Account and plan rules | See below |
Auto-expiring uploads (expires_in)
Pass expires_in (60–2,592,000 seconds, i.e. 1 minute to 30 days) to have an asset deleted automatically. Anything else is 400 validation_error; omit it for a permanent asset. It works on every upload path:
- Images: a form field for file uploads, or a JSON field next to
urlfor URL imports. Also accepted by batch, generate and edit. - Video:
X-PixelVault-Expires-Inon direct uploads,expires_inin the JSON body for URL imports and resumable-upload initiation. - Audio:
X-PixelVault-Expires-Inon direct uploads,expires_infor URL imports.
curl -X POST https://api.pixelvault.dev/v1/images \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-F "file=@preview.png" \
-F "expires_in=86400"
→ { "data": { "id": "img_abc123", "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
"expires_in": 86400, "temporary": true } } curl -X POST https://api.pixelvault.dev/v1/videos \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: video/mp4" \
-H "X-PixelVault-Filename: preview.mp4" \
-H "X-PixelVault-Expires-In: 604800" \
--data-binary @preview.mp4 Images echo "expires_in" and "temporary": true; videos and audio report expires_at and "temporary": true.
The hourly sweep
Deletion runs in a sweep at five past every hour (UTC). A few hourly runs are reserved for other maintenance and skip it, so removal can lag the TTL by up to about two hours. Don't use expires_in as an access control: until the sweep runs, the URL still serves. For exact cut-offs, make the asset private and control the link lifetime instead.
When a video or audio asset expires, PixelVault fails any active optimization, enrichment or transcription job, returns its reserved monthly allowance, and deletes the original plus every derivative: poster, social-ready copy, transcripts, and storyboards. Unfinished resumable upload sessions are aborted after 24 hours by the same sweep, releasing their reserved quota. No video TTL default exists: video is permanent unless you set one.
Keyless uploads
Image uploads without an API key are temporary: the response says "expires_in": 2592000 and "temporary": true, and the image is removed 30 days after upload by a storage rule. To keep an image without that fixed expiration, re-upload it with your API key and use the new URL; the original anonymous URL still expires. Browser-tool uploads at pixelvault.dev/tools without an account last up to 24 hours.
Link expiry is not deletion
sign_expires_in (and the expires_in body of a sign-url call) only sets how long one signed link to a private asset works. It never deletes bytes, and you can always mint a fresh link. Conversely, expires_in on upload deletes the asset no matter how many links are outstanding.
Collections
Closing a collection with POST /v1/collections/:id/close applies its cleanup policy: a closed ci_build collection's members are expired and removed by the next sweep. See Collections.
Account and plan retention
- Unverified accounts: an account whose email is still unverified 30 days after signup is deleted with all of its media and keys. Verify the email to keep it.
- Free plan: per the terms, free-plan images older than 6 months that haven't been accessed in 30 days may be cleaned up after a 14-day grace period.
- Paid plans retain media indefinitely. After a downgrade to free, free-plan rules apply; see Billing.
- Exports: an export archive can be downloaded for 24 hours after it completes.
Next steps
- Private media & signed URLs.
- Export all media before deleting a project.
- Rate limits & quotas.