Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

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.

MechanismWhat endsWhen
expires_inThe asset and all its derivatives are deletedAfter the TTL, at the next hourly sweep (up to about 2 hours late)
Keyless uploadThe anonymous image30 days after upload
sign_expires_in / expiresOne signed link; the asset staysExactly at expires
Delete endpointThe asset, its derivatives, and every linkImmediately
Closing a ci_build collectionIts membersAt the next sweep
Account and plan rulesSee 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 url for URL imports. Also accepted by batch, generate and edit.
  • Video: X-PixelVault-Expires-In on direct uploads, expires_in in the JSON body for URL imports and resumable-upload initiation.
  • Audio: X-PixelVault-Expires-In on direct uploads, expires_in for 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.

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