Expiry field reference for temporary file URLs
Upload returns an `expires_at` value so workflows can see when the public file URL should stop working and when cleanup should happen.
- Reviewed by
- GetFileURL technical team
- Updated
- Field
- expires_at
- Format
- ISO timestamp
- Response
- expires_at plus file_id
What this page answers
Read the expires_at field returned by upload. Store it with the file ID so retries and cleanup steps know the URL lifetime.
- Reviewed by
- GetFileURL technical team
- Last updated
Return exact expiry metadata for logs and branches.
Automation builders need to see when a URL stops working so they can plan retries and cleanup branches.
expires_at
Absolute timestamp for when the URL should stop resolving.
file_id
Identifier for early deletion before expiry.
url
The public CDN URL that remains valid until expiry or deletion.
Keep the upload request aligned with the live API.
The current upload request sends the file and visibility. The response carries the lifecycle fields the workflow should store.
file
Required multipart file field.
visibility
Optional upload field for public or signed delivery.
No upload-time expiry field
Do not send an upload-time expiry field. Read the returned `expires_at` instead.
Match expiry to the real fetch window.
The best retention window is long enough for the destination API to fetch the file and short enough that workflow files do not become unmanaged public assets.
Immediate fetch
OCR, AI, and webhook steps often need only enough time for retries and a short queue delay.
Async fetch
Social, CMS, and import APIs may fetch later, so compare their delay with the returned `expires_at`.
Manual review
If humans review the URL before the next step, use workspace retention settings that fit that process.
Use `expires_at` before every delayed branch.
The expiry field is most valuable when the workflow checks it before delayed work, not only when the upload succeeds.
Before retry
Compare the retry time with `expires_at`; re-upload instead of retrying a URL that may expire mid-fetch.
Before async handoff
For imports and publishing jobs, pass only URLs that survive the destination's later server-side fetch.
Before cleanup
If the destination has already fetched the file, call delete instead of waiting for expiry.
Lifecycle errors should be actionable.
A workflow builder should know whether to change the request, fix account limits, or retry later.
bad_request
The upload request is missing a required file field or has an invalid visibility value.
file_too_large
The file is larger than the current endpoint or account limit.
404 not_found
A later metadata or delivery check can report a file that is deleted, expired, missing, or not visible to the current key.
Copy the same upload shape into code
curl -X POST https://api.getfileurl.com/v1/files \
-H 'Authorization: Bearer $GETFILEURL_KEY' \
-F 'file=@invoice.pdf' \
-F 'visibility=public'Common questions
How do I see when a file URL expires?
Read the `expires_at` field returned by upload. Store it with the file ID so retries and cleanup steps know the URL lifetime.
Can I set expiry in the upload request?
Not with the current public upload contract. Upload with `visibility=public`, then use the returned `expires_at` and workspace retention settings.
How should I use the expiry timestamp?
Use `expires_at` to decide whether delayed fetches, retries, or user review need a fresh upload before continuing.
Can I remove a URL before expiry?
Yes. Use the returned file ID with the delete endpoint to remove public access early.