Files and media

Files live in S3-compatible object storage. The repository controller exposes about 25 file handlers under /repository/file/*, plus a customer-scoped subset and a Pexels-backed stock media search.

Uploading

multipart/form-data, field name file. Requires the create content permission.

curl -X POST https://appengine.appmint.io/repository/file/upload \
  -H 'Authorization: Bearer …' -H 'orgid: acme' \
  -F '[email protected]' \
  -F 'location=products/2026' \
  -F 'isPrivate=false'

Fetches a remote URL and stores it, with the same side effects as a direct upload.

{ "url": "https://example.com/a.png", "location": "imports", "name": "a", "thumbnails": true, "isPrivate": false }

The MIME type and extension are sniffed from the download (.svg is special-cased), and the object is written to <location>/<name>[.<ext>].

What an upload does

1. Scope the path to the org addOrgIdToPath prefixes the tenant, so every key is namespaced.

2. Clear stale thumbnails Any previous thumbnails for that key are deleted first — re-uploading over a path does not leave the old derivatives behind.

3. Write the object putObject into S3_BUCKET with the derived ContentType.

4. Apply the ACL Unless isPrivate, the object is set public-read.

5. Generate thumbnails Via sharp, unless disabled. Failures are logged and swallowed — the upload still succeeds without thumbnails.

6. Return the merged descriptor The file entry from a listing, merged with the thumbnail descriptors.

Thumbnails

Three sizes by default:

Override with the IMAGE_SIZES env var (JSON, e.g. {"xs":100,"sm":200,"md":400,"lg":800}). Only image extensions are processed — png, jpeg, jpg, gif, tiff, bmp, webp by default, configurable via IMAGE_EXTENSIONS.

Derivatives are stored beside the original under a thumbnails segment inserted at the second path position, with the size appended to the filename:

acme/products/2026/widget.jpg
acme/thumbnails/products/2026/widget_sm.jpg

Regenerate on demand:

Takes { location } — a single path or an array.

These variants are what BaseModel.post.images.meta.xs|sm|md points at, which is why an image referenced from a record already has responsive sizes available.

Reading files

Managing files

append and prepend are fully supported only by the local driver; on S3 they delegate to the underlying disk.

Listing

Paged, 100 keys per page by default. ?check-privacy=true resolves each object's ACL, which costs an extra call per key.

Listing options support prefix, maxKeys, pageNumber, startPage, recursive, endsWith, includes, thumbnail, foldersOnly and checkPrivacy.

Indexes a file location so it becomes searchable.

Favicons

Builds favicon.ico and favicon.png at the org bucket root from a source image (sharp + to-ico) and returns { ico: { signedUrl, path }, png: { signedUrl, path } }.

Customer-scoped files

Three parallel endpoints let an end user manage their own uploads without reaching the operator surface:

Stock media

Pexels-backed search, so the Studio asset picker can offer stock imagery inline:

Assets

Assets are records that describe files — searchable, taggable, and attached to other records.

Storage configuration