Files and the Media Library¶
Diagonal stores uploaded images, documents, audio, and other files as Files. You can upload them while editing a File field or add reusable assets to the Media Library.
Choose the right place¶
- Use a File field when the upload belongs to a Record, such as a customer's agreement or a product image.
- Use the Media Library for reusable builder assets, such as logos, page images, PDFs, and shared downloads.
- Use a public File only when anyone with its URL should be able to open it.
A Media Library item points to a File and adds a display name and folder location. Moving or renaming the library item doesn't change the File ID used by pages or Records.
Upload to the Media Library¶
- Open System Admin → Media Library.
- Choose Upload and select one or more files.
- Optionally create folders, move items, or rename an item's display name.
- Select an item from a page, rich-content editor, or other Media Library picker.
Diagonal's upload UI and synchronous API limit Files to 50 MB each. The direct-to-storage browser path applies that limit before upload; the temporary upload URL itself doesn't validate the uploaded byte size. The library can show image previews and stores image dimensions when they are available.
Only System Administrators can manage the Media Library. Package-owned items may also be read-only when the package's policy doesn't allow changes.
Configure a File field¶
When adding a File field to a Resource, choose:
- Accepted file types to limit MIME types, such as images or PDFs.
- Visibility: Private is the default; Public makes the File available without authentication.
A File field stores a File reference, not an object-store URL. Pages and APIs resolve that reference through Diagonal's stable file endpoint.
Private and public access¶
Private¶
Private Files require a permitted path to the File. For a File attached to a Record, the caller must be able to read that Record and the File field must be visible under its Resource Policies. Private conversation and workflow-run attachments inherit the access rules of those surfaces.
Use Private for contracts, identity documents, internal exports, customer uploads, and any content that shouldn't be available to an anonymous visitor.
Public¶
Public Files can be opened without signing in. Use Public for site imagery, public downloads, and other intentionally shareable assets.
Changing visibility changes access
Promoting a File to Public makes it reachable without Resource Policy checks. Don't use Public as a workaround for a page that can't load a private File; fix the relevant Record and Field access instead.
Use the Files API¶
Upload a binary as multipart/form-data to POST /api/files/uploads. The response contains a temporary key. Use that key promptly as the value of a File field or when creating a Media Library item.
For large browser uploads, request a temporary upload URL from POST /api/files/uploads/temporary-url. File metadata is available at GET /api/files/{file} when the caller can access the File.
Temporary upload keys are staging values. Persist the File value returned by the final Record or Media Library operation rather than retaining the temporary key.
Troubleshooting¶
- Upload rejected: confirm the file is 50 MB or smaller and matches the Field's accepted MIME types. API uploads enforce the size limit server-side; direct-to-storage uploads rely on the browser uploader's check.
- File returns access denied: for a private Record File, check the Resource Policy, Record filter, and Field visibility. Being able to open the Page alone doesn't grant access to its data.
- Package asset can't be edited: inspect the installed package's ownership policy. Update through the package when the asset is package-managed.
- Broken saved link: store File IDs or values supplied by Diagonal, not temporary object-store URLs.