space.fs.buckets

List, create, read, rename, and delete a project’s buckets, and make them public or private.

A bucket holds a project’s files, and its name is the first part of every path, such as invoices in invoices/2026/0001.pdf. These functions manage the buckets themselves. For the files in them, use the other space.fs functions.

Every bucket name is 3 to 63 lowercase letters, digits, and single hyphens, starting and ending with a letter or digit, and unique in the project. A project holds at most 10 buckets. See Limits.

Every function here rejects with a SpaceError and never throws before it returns. When an argument is wrong, nothing is sent. Every call can also fail with the codes listed on SpaceError, such as timeout and network_error, and with forbidden when the API key may not manage buckets.

`space.fs.buckets.list()`

Lists the project’s buckets by name.

space.fs.buckets.list(options?: {
  signal?: AbortSignal
  timeoutMs?: number
}): Paged<Bucket>

Parameters

options.signalAbortSignal: Cancels each page’s request when it aborts. The page 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 Paged<Bucket>, straight away and without a promise. Nothing is sent until you read from it. Go through every Bucket with for await, load one page of up to 200 with page(cursor?), or load them all with all(). space.fs.list() explains each way.

Example

list-buckets.ts

import { space } from "digitospace"

for await (const bucket of space.fs.buckets.list()) {
  console.log(`${bucket.name}: ${bucket.objectCount} files, ${bucket.bytesStored} bytes`)
}

`space.fs.buckets.create()`

Creates a bucket. It starts private: make it public with update().

space.fs.buckets.create(
  name: string,
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<Bucket>

Parameters

namestringRequired: The bucket’s name: 3 to 63 lowercase letters, digits, and single hyphens, starting and ending with a letter or digit.
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 Bucket.

Errors

Code	When
`validation_failed`	The name breaks the rules above
`bucket_name_taken`	Another bucket in the project has that name
`bucket_limit_reached`	The project already holds as many buckets as it can

Example

create-bucket.ts

import { space } from "digitospace"

const bucket = await space.fs.buckets.create("invoices")

console.log(bucket.id, bucket.visibility)

`space.fs.buckets.get()`

Gets one bucket, with how many files it holds and their size.

space.fs.buckets.get(
  bucket: string,
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<Bucket>

Parameters

bucketstringRequired: The bucket’s name, such as invoices.
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 Bucket.

Errors

Code	When
`validation_failed`	The name breaks the rules above
`not_found`	The bucket does not exist

Example

bucket-size.ts

import { space } from "digitospace"

const bucket = await space.fs.buckets.get("invoices")

console.log(`${bucket.objectCount} invoices, ${bucket.bytesStored} bytes`)

`space.fs.buckets.update()`

Renames a bucket, makes it public or private, or both. Its files stay where they are, and their keys do not change.

space.fs.buckets.update(
  bucket: string,
  change: {
    name?: string
    visibility?: "private" | "public"
  },
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<Bucket>

After a rename, paths use the new name, such as invoices-2026/0001.pdf in place of invoices/0001.pdf.

Parameters

bucketstringRequired: The bucket’s current name.
change.namestring: A new name, under the same rules as any bucket name.
change.visibilitystring: private, where only an API key or a console session that may read the project’s files can reach them, or public, where anyone with a file’s address can open it. See Share files publicly.
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.

change must hold name, visibility, or both, and nothing else.

Returns

A promise for the changed Bucket.

Errors

Code	When
`validation_failed`	A name breaks the rules above, `visibility` is not `private` or `public`, or `change` is empty or holds another field
`not_found`	The bucket does not exist
`bucket_name_taken`	Another bucket in the project has the new name
`public_buckets_unavailable`	Buckets cannot be made public yet

Example

rename-bucket.ts

import { space } from "digitospace"

const bucket = await space.fs.buckets.update("invoices", {
  name: "invoices-2026",
  visibility: "private",
})

console.log(bucket.name)

`space.fs.buckets.delete()`

Deletes an empty bucket. With force: true, it deletes the bucket and every file in it. This cannot be undone.

space.fs.buckets.delete(
  bucket: string,
  options?: {
    force?: boolean
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<void>

Parameters

bucketstringRequired: The bucket’s name.
options.forceboolean: true to delete the bucket and every file in it. The bucket disappears at once, its files are removed shortly after, and uploads in progress are cancelled. false by default, when a bucket that holds files is refused.
options.signalAbortSignal: Cancels the call when it aborts. The promise then rejects with aborted, and the bucket may or may not be deleted.
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 that resolves with no value once the bucket is deleted.

Errors

Code	When
`validation_failed`	The name breaks the rules above
`not_found`	The bucket does not exist
`bucket_not_empty`	The bucket still holds files, and `force` is not `true`

Example

delete-bucket.ts

import { space } from "digitospace"

await space.fs.buckets.delete("invoices-2025", { force: true })

Last updated 30 September 2026