space.fs.copy()

Copy a file to another key, in the same bucket or another bucket in the project.

Copies a file to another path, in the same bucket or another bucket in the same project. The original stays where it is. A file already at the new path is replaced.

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

Parameters

fromstring | { bucket, key }Required: The file to copy: 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 put the copy, 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.
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 new File, at to. It keeps the original’s media type.

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 files

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

Example

archive-invoice.ts

import { space } from "digitospace"

const copy = await space.fs.copy(
  "invoices/2026/0001.pdf",
  "archive/2026/dar-es-salaam/0001.pdf"
)

console.log(`Copied to ${copy.key}`)

Last updated 30 September 2026