Storage

Storage is RevoEngine’s durable file and folder system. Use it for uploaded source files, generated reports, integration payloads, attachments, Agent artifacts, and operational evidence that must remain addressable by a stable storageEntryId. Storage owns more than bytes. A file entry also carries its location, version, content type, metadata, effective access, retention, archive state, and any derived index used for bounded reads.

The four objects to distinguish

Object	Meaning	Stable after upload?
Workspace	An authorized view of a Storage area, such as Explorer, Private, an Agent workspace, or another managed product area	Yes
Folder entry	A hierarchy and access boundary	Yes
File entry	A published, readable file identified by `storageEntryId`	Yes
Upload session	A temporary control record for transferring or assembling one file	No

An upload session is not a file. It reserves the intended target and records upload progress, lease, access, retention, metadata, schema, and compute policy. It cannot be read with getFileData() and must not be used as a storageEntryId. The file becomes durable and readable only when the session reaches FINALIZED.

RESERVED -> UPLOADING -> FINALIZING -> FINALIZED
                  |             |
                  +-> ABORTED    +-> FAILED
                  +-> EXPIRED

Treat FINALIZED as the publication boundary. Issuing an upload URL, accepting one part, or completing a byte-transfer request is not enough to trigger downstream processing.

Choose the write path

Need	Recommended path	Who finalizes?
Complete small text or binary payload is already in the caller	`storage.putObject()` or `POST /storage/objects`	The call
Browser or frontend uploads one complete file	Direct upload session and returned temporary target	Storage automatically after confirming the transfer
One producer generates ordered parts	Incremental upload session	Caller
Concurrent, out-of-order, or repairable parts	Chunked upload session	Caller
External HTTP response should become a file	`api.httpCall(..., { responseType: 'storage', target })`	Runtime bridge
Existing file should become an HTTP request body	`api.httpCall(..., { requestType: 'storage', source })`	No new entry unless a target is also supplied
SFTP import or export	`transport.sftpImport()` / `transport.sftpExport()`	Runtime bridge for imports

Do not create an upload session for every write. A session is useful when bytes arrive outside the current call, the payload is large, parts must be retried, or a structured file is assembled over several calls.

Two independent session settings

uploadMode and writeMode answer different questions.

Setting	Values	Controls
`uploadMode`	`direct`, `chunked`, `incremental`	How bytes or parts reach Storage
`writeMode`	`staged`, `direct`	How structured CSV/XLSX row parts are materialized

writeMode: 'direct' does not mean “return an upload URL.” It is a structured-writer optimization for a fixed, declared CSV/XLSX layout. Ordinary browser uploads choose uploadMode: 'direct' and normally leave writeMode at its default. See Upload sessions for the complete lifecycle and Structured files for schemas, types, and parser behavior.

Read by format

Use the narrowest reader that matches the file:

Content	Low-code API
File or folder metadata	`storage.getEntry()` / `storage.getFile()`
Bounded text or extracted document text	`storage.getDocument()`
CSV, TSV, XLSX, NDJSON/JSONL, JSON array, or record-oriented XML	`storage.getFileData()`
Full scan of CSV/TSV, XLSX, NDJSON/JSONL, a JSON array, or record-oriented XML	`storage.walkFileData()`
Reusable row, worksheet, or line index	`storage.getFileStats()`
Temporary download or preview	`storage.getDownload()`

Structured reads return a page with rows, headers, columns, next, and nextCursor. Copy the cursor exactly and keep pages bounded. In record mode, walkFileData() processes the same record formats in awaited batches; it does not treat plain text, a top-level JSON object, or binary files as rows. For XML, provide recordPath; for a specific Excel worksheet, provide sheet. Do not parse CSV by splitting on commas or newlines. Quoted separators, escaped quotes, and multiline records are valid CSV. CSV syntax and source field counts are validated before record processing. Invalid input fails with STORAGE_CSV_INVALID and bounded location diagnostics by default. Explicit onError: 'skipRow' skips only records with the wrong field count and reports their original locations; syntax and record-size errors still abort. CSV statistics distinguish logical rowCount from actual physical lines, including headers and blanks. Explicit mode: 'lines' is available for custom text workflows; it returns raw strings without CSV interpretation. See Structured files for dialect, validation and line-count semantics.

Workspaces and access

The Platform API exposes the Storage workspaces available to the current identity. A workspace is a governed view, not a separate file format or upload protocol. Its policy decides whether the caller may list, read, create folders, or upload. Access is evaluated from the entry and its ancestors:

restricted: false uses the workspace’s normal visibility rules;
restricted: true limits access to authorized users, groups, owners, or administrators;
a restricted ancestor remains effective even if a child is not marked restricted;
a namespace, folder ID, or signed URL never grants access by itself.

Resolve logical paths at runtime instead of copying folder UUIDs between instances. Use resolveFolderPath() when the path must already exist and ensureFolderPath() when authorized code may create missing segments.

Retention and lifecycle

Upload-session expiry and file retention are separate:

session expiresAt limits how long the unfinished upload can remain active;
retention.ttlSeconds starts only after finalization;
retention.expiresAt sets an absolute file expiry;
retention: null means no expiry;
omitting retention uses the destination’s default on create and preserves it on update.

An expired file becomes unavailable and is archived with TTL_EXPIRED before later cleanup. Manual archive is recoverable while the entry remains archived; permanent delete is a distinct, destructive operation. Use optimistic version checks for update, move, archive, restore, delete, and replacement flows.

Compute policy

computeStats controls when Storage builds reusable text or structured-file indexes:

Value	Behavior
`sync`	Build during finalization; completion waits for the result
`async`	Publish the file, then build in the background
`none`	Defer work until a later `getFileStats()` or structured read needs it

With sync, finalization persists the supported file statistics with the entry and its STORAGE_CREATED or STORAGE_UPDATED event. The event and response contain statistics for the same uploaded version, even if another upload later replaces that file. XML uploads initially contain physical text statistics; structured XML indexing requires an explicit recordPath on the read. CSV, TSV, XLSX, and text uploads default to synchronous computation. Other binary uploads default to none. Choose sync when the next operation immediately needs rows, worksheet metadata, or line ranges. Choose async when file availability matters more than immediate indexing.

Failure and retry rules

If a direct transfer returns successfully but confirmation is uncertain, read the session. Continue only after FINALIZED.
If a part call times out, read the manifest before sending data again. Incremental retries can otherwise create an additional part.
A fresh matching target can return STORAGE_UPLOAD_IN_PROGRESS; inspect or recover the existing session instead of creating parallel writers.
Abort abandoned active sessions as best-effort cleanup.
A version conflict means the target changed. Reload the entry before deciding whether to replace it.
Temporary upload and download URLs are credentials. Never persist or log them.
Make downstream Event and Job processing idempotent against the source entry ID and version.

Storage versus legacy Files

Use Storage for all new work. The legacy Files API uses fileId and a different lifecycle. Do not mix fileId, storageUploadSessionId, and storageEntryId. Maintain the legacy API only when an existing integration explicitly depends on it. See Files (legacy).

Next steps

Upload sessions

Implement direct, incremental, and chunked uploads with the correct completion boundary.

Structured files

Declare one CSV/TSV/XLSX schema and choose fallback or strict validation.

HTTP integrations

Stream Storage sources and targets through external HTTP calls.

SDK storage and batching

Use sessions and bounded reads from Node.js.

Storage low-code reference

Inspect the current storage.* signatures.

Platform API reference

Inspect exact HTTP operations and DTOs.

Application interfaces

Data

Files

Automation

Collaboration and realtime

Observability

Identity and security

The four objects to distinguish

Choose the write path

Two independent session settings

Read by format

Workspaces and access

Retention and lifecycle

Compute policy

Failure and retry rules

Storage versus legacy Files

Next steps

Upload sessions

Structured files

HTTP integrations

SDK storage and batching

Storage low-code reference

Platform API reference

​The four objects to distinguish

​Choose the write path

​Two independent session settings

​Read by format

​Workspaces and access

​Retention and lifecycle

​Compute policy

​Failure and retry rules

​Storage versus legacy Files

​Next steps

Upload sessions

Structured files

HTTP integrations

SDK storage and batching

Storage low-code reference

Platform API reference

The four objects to distinguish

Choose the write path

Two independent session settings

Read by format

Workspaces and access

Retention and lifecycle

Compute policy

Failure and retry rules

Storage versus legacy Files

Next steps