space.fs.move()

Move or rename a file, within a bucket or to another bucket in the project.

Moves a file to another path, in the same bucket or another bucket in the same project. Use it to rename a file too. A file already at the new path is replaced.

space.fs.move(
  from: string | { bucket: string; key: string },
  to: string | { bucket: string; key: string },
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<StoredFile>

A move is two steps: it copies the file to to, then deletes the file at from. It is not one step that happens all at once.

If the copy fails, nothing has changed.
If the delete fails, the promise rejects and the file is at both paths. Call move again, or delete from yourself.

Parameters

fromstring | { bucket, key }Required: The file to move: bucket/key as one string, such as invoices/2026/0001.pdf, or an object such as { bucket: "invoices", key: "2026/0001.pdf" }.
The bucket is 3 to 63 lowercase letters, digits, and single hyphens, starting and ending with a letter or digit.
The key is 1 to 1,024 bytes. It cannot start or end with /, hold //, have a folder named . or .., or hold control characters.
tostring | { bucket, key }Required: Where to move it, in the same form and under the same rules as from. It must differ from from.
options.signalAbortSignal: Cancels the call when it aborts. The promise then rejects with aborted. If the copy has already finished, the file may be at both paths.
options.timeoutMsnumber: The longest each request may take, in milliseconds. The client’s timeoutMs when you leave it out, 30,000 by default.

Returns

A promise for the File at its new path.

Errors

The promise rejects with a SpaceError. The call never throws before it returns the promise, and when an argument is wrong, nothing is sent.

Code	When
`validation_failed`	A path is wrong. `issues` names each field, such as `from.key` or `to.bucket`
`invalid_request`	`to` is the same as `from`
`not_found`	Either bucket, or the file, does not exist. `resource` says which
`storage_quota_reached`	The copy does not fit in the project’s storage
`taken_down`	We took the file or its bucket down because it broke our terms
`forbidden`	The API key may not upload or delete files. A move needs both

Every call can also fail with the codes listed on SpaceError, such as timeout and network_error.

Example

rename-invoice.ts

import { space } from "digitospace"

const moved = await space.fs.move(
  "invoices/drafts/0001.pdf",
  "invoices/2026/0001.pdf"
)

console.log(`Now at ${moved.key}`)

Last updated 30 September 2026