Skip to main content

​
Update a file

The body is strict. Unknown fields are rejected.
The change is rejected when:
  • the file has active retention,
  • the file’s bucket has active retention,
  • the caller lacks file:write,
  • the body contains an unknown key.
A no-op update can return an empty string in data. Treat the HTTP status as the success signal, then re-read the file if you need the new state.
version is accepted for compatibility with the frontend’s mutation flow. It is not a general-purpose compare-and-swap contract. Do not build conflict detection solely on it.

​
Move a file

Cross-bucket moves are allowed only within the same company. A destination folder must belong to the destination bucket. Response:
destinationBucketId is omitted when the move stays in the same bucket.

​
Copy a file

The copy duplicates the stored bytes and consumes storage capacity. The new file’s display name gets a (copy) suffix. Response:
If capacity is insufficient, the copy fails with 402. The original is not modified.

​
Soft-delete and hard-delete

The query value is case-insensitive. A soft delete:
  • blocks when the file has active retention,
  • blocks when the bucket has active retention,
  • blocks when a legal hold applies,
  • keeps the bytes stored and billed until purge.
A hard delete:
  • blocks while retention is active,
  • blocks while a legal hold applies,
  • removes all versions,
  • returns 410 if the item was already purged after the display window.
The success payload is an empty string rather than an object. Check the HTTP status.
Hard deletion is irreversible. Build an explicit confirmation step and never expose it as the default action.

​
Restore from trash

The restore payload is nested, and the HTTP status is always 200 when the controller returns a service result. The real outcome is in data.status: Read data.data.fileId on success, and branch on data.status for failures. Errors thrown before the service result — permission failures, for example — use normal HTTP error codes. Before showing destructive actions, read the file’s retention state from a list response or folder content:
  • isRetention: true means an active lock.
  • retentionPeriod shows the configured period.
  • Bucket retention is visible on bucket records.
Legal hold is not exposed as a field on file responses. If a delete unexpectedly returns 403, a legal hold may be the cause.

​
Lifecycle checklist

Renames use PUT /files/update/{fileId} with only allowed fields.
Moves and copies validate the destination bucket and folder before the request.
Soft delete is the default; hard delete requires explicit confirmation.
Retention and legal hold are checked before offering delete.
Restore handles 400, 404, and 410 distinctly.
Copy operations account for storage capacity.