space.fs.read()

Download a file’s contents as bytes, text, JSON, a Blob, a stream, or the raw response.

Downloads a file’s contents into your server. The as option decides what the promise resolves to, and the return type follows it. To hand a file to someone else instead, use space.fs.url().

space.fs.read(
  path: string | { bucket: string; key: string },
  options?: {
    as?: "bytes" | "text" | "json" | "blob" | "stream" | "response"
    preset?: string
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<Uint8Array | string | unknown | Blob | ReadableStream<Uint8Array> | Response>

Parameters

pathstring | { bucket, key }Required: The file to read: 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.
options.asstring: What to resolve to. bytes when you leave it out.
as Resolves to
bytes Uint8Array
text string, decoded as UTF-8
json unknown, the parsed JSON. Check its shape before you use it
blob Blob
stream ReadableStream<Uint8Array>, for large files you pass on without holding them in memory
response Response, the download’s own response with its status and headers
options.presetstring: The name of a preset to resize an image to, such as thumb. 1 to 64 characters.
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. The time runs until the whole file has been read, so allow more for a large file. A whole number from 1 to 600,000.

`as`	Resolves to
`bytes`	`Uint8Array`
`text`	`string`, decoded as UTF-8
`json`	`unknown`, the parsed JSON. Check its shape before you use it
`blob`	`Blob`
`stream`	`ReadableStream<Uint8Array>`, for large files you pass on without holding them in memory
`response`	`Response`, the download’s own response with its status and headers

Returns

A promise for the file’s contents, in the form as asks for.

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`	The path or the preset is wrong. `issues` names each field, such as `path.key`
`not_found`	The bucket, the file, or the preset does not exist
`taken_down`	We took the file or its bucket down because it broke our terms
`download_failed`	Storage could not send the file
`unexpected_response`	With `as: "json"`, the file is not JSON
`forbidden`	The API key may not download files

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

Example

read-settings.ts

import { space } from "digitospace"

const notes = await space.fs.read("notes/2026/09/dar-es-salaam.txt", { as: "text" })
console.log(notes)

const settings = await space.fs.read("config/shop.json", { as: "json" })
console.log(settings)

Pass a large file on without holding it in memory:

app/invoices/route.ts

import { space } from "digitospace"

export async function GET() {
  const body = await space.fs.read("invoices/2026/0001.pdf", { as: "stream" })
  return new Response(body, {
    headers: { "Content-Type": "application/pdf" },
  })
}

Last updated 30 September 2026