Skip to main content
Files is the legacy integration object model. It is retained so existing applications can browse paths, create folders or file records, upload through signed URLs, preview, download, and soft-delete historical objects.
Do not use legacy Files for a new integration. The current public surface does not provide Storage-equivalent ACLs, retention, resumable sessions, move, archive/restore lifecycle, workspaces, or optimistic replacement semantics.

​
Current public contract

The current backend Files controller does not expose a public move, archive, restore, ACL, retention, or multipart-session endpoint. Do not build a recovery promise around frontend compatibility controls that are not backed by the current public API.

​
Path-oriented identity

Files stores fileName separately from path:
  • fileName cannot contain /;
  • a non-empty path cannot begin or end with /;
  • the target path must already exist;
  • root objects use path: null;
  • the stable API reference is still fileId, not the reconstructed display path.
force: true lets the legacy service replace a conflicting path/name record. This is not the same as Storage replacement: it does not use the caller-observed entry version as an optimistic concurrency guard.

​
Legacy direct upload

The browser flow is:
The single-file size is checked against the instance’s filesSingle quota when the record is created. The returned upload constraints, file identifier, and actor metadata bind the managed upload to that record. A successful byte transfer is not a reason to invent a new durable contract around Files. Re-query the fileId before downstream work and use the legacy FILE_FINALIZED event only while maintaining an existing event integration.

​
Legacy event topics

Legacy upload lifecycle events are normalized as:
  • FILE_FINALIZED;
  • FILE_DELETED;
  • FILE_ARCHIVED;
  • FILE_UPDATED for supported metadata updates.
These topics carry the legacy File upload envelope, not a Storage entry. New pipelines should upload into Storage and use STORAGE_CREATED, or STORAGE_SYNCHRONIZED when asynchronous text statistics must be ready before work starts.

​
What Storage adds

​
Migrate an existing fileId workflow

1

Inventory references

Find application rows, Component inputs, Events, dashboard definitions, and external systems that persist fileId or a Files path.
2

Create the governed destination

Create or ensure a Storage folder. Configure the effective User/Group ACL and retention before moving production traffic.
3

Copy and finalize

Read the legacy object through its temporary download URL, stream it into a Storage target, and wait for a finalized storageEntryId.
4

Update consumers

Persist the new storageEntryId; change Components to the current storage.* API and Events to Storage lifecycle topics.
5

Verify the execution principal

Preview, download, batch-read, and process the object as the real user or Job service account—not only as an administrator.
6

Retire the legacy object

Stop new writes, observe the migrated workflow, and soft-delete the legacy record only after every consumer uses Storage.
Copying bytes is only half of migration. Identity, ACL, retention, events, and every persisted reference must move before the old fileId can be retired.

​
New code uses Storage

Legacy low-code file helpers and signed Files URL helpers remain compatibility-only. This guide intentionally does not publish their signatures or examples. New implementations use:
  • storage.getFile() and storage.getText();
  • storage.getFileStats() and storage.getFileData();
  • storage.putObject();
  • storage.createUploadSession() with uploadPart() and finalizeUploadSession();
  • storage.archiveEntry(), restoreEntry(), and deleteEntry();
  • Storage source and target objects in api.httpCall().
See Storage for the complete lifecycle, HTTP and Storage for streamed migration, and the generated Storage method reference for current signatures only.
Last modified on September 5, 2026