EN Media and Files

Media uploads, quotas and signed URLs

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

The v0.5.1 media backend uses the local filesystem. S3/R2 object-storage adapters are not implemented capabilities in this release. Physical files and internal-database metadata are managed together; public responses do not expose storage keys.

{
  "media": {
    "enabled": true, "backend": "local",
    "local_directory": "./data/media-files",
    "max_upload_bytes": 10485760, "max_batch_files": 5,
    "max_owner_bytes": 104857600,
    "allowed_mime_types": ["image/png", "image/jpeg", "application/pdf"],
    "allowed_extensions": ["png", "jpg", "jpeg", "pdf"],
    "public": false, "owner_delete_only": true,
    "deduplicate": true, "deduplicate_scope": "owner",
    "signed_urls_enabled": false
  }
}

Endpoint family

The project prefix contains media, media/_batch, ID-based download/delete, metadata and signed-URL routes. Consult project OpenAPI for multipart field names and methods. ForgeClient.request(files=...) supports multipart; the SDK does not automatically retry requests containing files.

Permissions and quotas

Upload/read/delete/admin permissions default to media.upload, media.read, media.delete and media.admin. owner_delete_only and public access settings also apply. A transactional quota ledger coordinates concurrent uploads for an owner.

max_upload_bytes limits one file. Proxy and project body limits also bound the full HTTP request; several files in one batch can exceed that combined limit. MIME/extension allowlists are not malware scanning. Add content validation/scanning if required by your application.

Deduplication and consistency

Owner-scoped deduplication is the default to avoid unintentionally sharing visibility between owners. Hash checks establish content integrity, not publisher identity or file safety. If metadata persistence fails, orphan-file cleanup is attempted; operational backups and consistency checks remain necessary.

Inspect every item result in a batch response. Partial success is not one all-or-nothing batch transaction. Post-upload hooks are not durable background jobs.

Signed URLs

Temporary access requires signed_urls_enabled, a strong signing_secret and a bounded signed_url_ttl_seconds. Anyone holding a valid URL can use its access until expiry; sharing it in logs/messages also shares that capability. Default TTL is 300 seconds, with a maximum of 86400.

Multiple hosts and backups

A file on one host is not automatically present on another. Back up the media directory and metadata database consistently and test restoration. Without shared-storage design, load-balanced downloads can reach the wrong host and return 404 or inconsistent data.

Editor team attachments are a separate management feature from the application media API.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/media.py
• main/framework/config.py
• main/framework/routers/project.py
• exampleApps/app/MediaLibrary/config/40-media.json

---

English home · All English pages · Version maintenance