Files and temporary links
Util artifacts (screenshots today; HTML, Postman collections, video, JSON - later) are stored in the file service. The web app does not serve files from util rows directly - it shows temporary access links issued per request.
This page describes what you see in the UI and the limits that matter when integrating or building views.
What you see
On util details (e.g. Screenshot Multi), each screenshot has:
| Concept | In the UI |
|---|---|
| Preview | Image in the gallery when a valid preview link exists |
| File identity | Stable file id for the artifact (same id across refreshes) |
| Expiry | Preview may stop working after some time - not a broken file |
Legacy field image URL on a screenshot row matches the preview when the server resolved it successfully.
Temporary links (important)
Access links are presigned URLs: they work for a limited time, then return forbidden/expired.
| Link type | On util details (MVP) | When you need it |
|---|---|---|
| Preview (inline) | Resolved when you open details | Gallery, thumbnails |
| Download (attachment) | Not included in details response | Save file, export - request when user clicks download |
If a preview stops loading:
- Reopen details - server batch-refreshes preview links, or
- Use download / refresh in the UI when implemented - single-file link from the file bridge.
Do not cache preview URLs in external tools beyond their lifetime.
File categories (product)
| Category | Used for |
|---|---|
| screenshot | Screenshot Multi and visual util output |
| html | Planned |
| postman | Planned |
| video | Planned |
| json | Planned |
Files are bound to a parent entity (e.g. a util run) and a category so listing and access checks stay scoped to your team.
Upload from the UI
The product supports uploading screenshot files into the file service from the browser (same storage as runner-produced shots), bound to a util run or other entity when the screen provides upload.
Upload flow uses your session to obtain a short-lived token, then sends the file to the file service. Storage quota may be checked before upload when billing limits apply.
Limits (backend, user-visible effects)
| Limit | Effect |
|---|---|
| Link TTL | Previews/downloads expire; refresh or reopen details |
| Details performance | Many screenshots → details may take longer while previews are prepared (MVP: preview only, parallel resolve) |
| Team storage quota | Upload or new files may be rejected when quota is exceeded |
| File service unavailable | Details load without previews; file block may be empty - data row still shows capture metadata |
| Access | Links are for your team context; other teams cannot open them |
Internal service URLs and bridge paths are not part of the public contract - use the web app or documented API session.
See also
| Version | 1.2.1 |
| Last updated | 2026-06-28 |