FiloraFS-Lite API reference

Browser API testing

Run FiloraFS-Lite and open http://localhost:8080/api-test. The public tester prefills only the known development key, filorafs-local-dev-key. If you override the server key, enter it manually; the tester does not fetch the configured secret and keeps entered keys only in page memory.

Alternatively, import FiloraFS-Lite.postman_collection.json, set baseUrl and apiKey, choose a supported upload, and run upload → list → metadata → download → delete. Upload saves the generated filename as a collection variable.

FiloraFS-Lite Postman collection

File endpoints

Use the generated stored filename for subsequent operations, not the original upload name. Paths accept one flat filename; no endpoint defines query parameters.

FiloraFS-Lite endpoints
Method	Path	Purpose
POST	/file	Upload a multipart file
GET	/file/{filename}	Stream a stored file as an attachment
GET	/file/list	List stored filenames
GET	/file/info/{filename}	Read filesystem metadata
DELETE	/file/{filename}	Delete a stored file

POST/fileX-API-KEY

Upload one PNG, JPEG, PDF, or WebP file. Returns 200 with the UUID-based stored filename as plain text, without JSON quotes. The allowed extension is lowercased; original filenames are not used as storage paths.

Headers

X-API-KEY: <configured-key>
Content-Type: multipart/form-data; boundary=<client-generated-boundary>

Parameters

file — required multipart file part

Successful response

Example 200 response

4d95df24-3ae8-4e7c-a598-7ae7f40b24cc.pdf

Relevant errors

400 for an empty file, unsupported extension, or mismatch between extension, declared media type, and content signature.
Spring enforces the configured multipart file and request limits (10 MB each by default).

cURL

curl -X POST http://localhost:8080/file \
  -H "X-API-KEY: <configured-key>" \
  -F "file=@architecture.pdf;type=application/pdf"

GET/file/{filename}X-API-KEY

Returns 200 with a streamed Resource and Content-Disposition: attachment. Spring derives Content-Type from the stored filename, falling back to application/octet-stream.

Headers

X-API-KEY: <configured-key>

Parameters

filename — stored filename returned by upload

Relevant errors

404 when the file is missing, a symbolic link, or not a regular file.

GET/file/listX-API-KEY

Returns 200 with a sorted JSON array of regular filenames, or [] for empty storage. Symbolic links and directories are excluded. There is no pagination or ownership filtering.

Headers

X-API-KEY: <configured-key>

GET/file/info/{filename}X-API-KEY

Returns 200 with a FileMetadata JSON object: name, sizeKB (whole bytes / 1024, rounded down), mimeType (filename-derived), and lastModified (ISO-8601 UTC timestamp). Absolute filesystem paths are not returned.

Headers

X-API-KEY: <configured-key>

Parameters

filename — stored filename returned by upload

Relevant errors

404 when the file is missing, a symbolic link, or not a regular file.

DELETE/file/{filename}X-API-KEY

Returns 200 with the JSON boolean true when deleted or false when the file does not exist.

Headers

X-API-KEY: <configured-key>

Parameters

filename — stored filename returned by upload

Relevant errors

400 when the stored item is a symbolic link or directory.

Access model

ApiKeyFilter protects /file and /file/** with X-API-KEY. Missing or incorrect keys return 401 with the plain-text body Unauthorized. OPTIONS requests pass through without enabling a permissive CORS policy.

File operations reject absolute or nested paths and enforce containment under the storage root. Invalid names return 400; rejected traversal paths return 403. Storage I/O failures return 500.

Health endpoint

GET/actuator/healthPublic

Returns health status without components or details. A healthy application returns 200 with the response below. Other Actuator endpoints and discovery are not exposed by default.

Successful response

Healthy response

{"status":"UP"}