Files

The files resource manages objects within a bucket: streaming uploads, paging through listings, fetching metadata, and deleting individual files.

upload

files.uploadPUT/v1/buckets/{id}/files/{path}

files.upload(
  bucketId: string,
  path: string,
  body: BodyInit,
  contentType?: string,
  options?: { optimization?: "none" | "light" | "balanced" | "maximum" }
): Promise<FileInfo>

Streams a request body to a file at path inside the bucket. The body accepts any BodyInit (Blob, Buffer, ReadableStream, string). Pass an explicit contentType to override the default sniffed from the path.

Name	Type	Default	Description
optimization	"none" \| "light" \| "balanced" \| "maximum"	"none"	Override the bucket's optimizationMode for this upload. Sent as the X-Buckt-Optimization header.

const file = await client.files.upload(
  "bkt_01H8XYZABCDEFGHJKMNPQRSTVW",
  "logos/logo.png",
  new Blob([imageBytes], { type: "image/png" }),
  "image/png",
  { optimization: "balanced" }
);

console.log(file.url);

{
  "object": "file",
  "id": "fil_01H8XYZABCDEFGHJKMNPQRSTVW",
  "key": "logos/logo.png",
  "lastModified": "2026-04-25T12:34:56Z",
  "size": 24576,
  "contentType": "image/png",
  "url": "https://files.example.com/logos/logo.png"
}

list

files.listGET/v1/buckets/{id}/files

files.list(
  bucketId: string,
  opts?: { prefix?: string; cursor?: string; limit?: number }
): Promise<{ data: FileInfo[]; meta: CursorMeta }>

Lists files within the bucket. Cursor-paginated. Use prefix to narrow to a virtual subdirectory.

Name	Type	Default	Description
prefix	string	—	Restrict to keys starting with this prefix (e.g. "logos/").
cursor	string	—	Opaque cursor returned from a previous call. Omit for the first page.
limit	number	25	Page size. Maximum 100.

const { data, meta } = await client.files.list(
  "bkt_01H8XYZABCDEFGHJKMNPQRSTVW",
  { prefix: "logos/", limit: 50 }
);

for (const file of data) {
  console.log(file.key, file.size);
}

{
  "data": [
    {
      "object": "file",
      "id": "fil_01H8XYZABCDEFGHJKMNPQRSTVW",
      "key": "logos/logo.png",
      "lastModified": "2026-04-25T12:34:56Z",
      "size": 24576,
      "contentType": "image/png"
    }
  ],
  "meta": { "limit": 25, "nextCursor": null }
}

get

files.getGET/v1/buckets/{id}/files/{path}

files.get(bucketId: string, path: string): Promise<FileInfo>

Fetches metadata for a single file by path. Throws NotFoundError if the file or bucket is missing.

const file = await client.files.get(
  "bkt_01H8XYZABCDEFGHJKMNPQRSTVW",
  "logos/logo.png"
);

console.log(file.contentType, file.size);

{
  "object": "file",
  "id": "fil_01H8XYZABCDEFGHJKMNPQRSTVW",
  "key": "logos/logo.png",
  "lastModified": "2026-04-25T12:34:56Z",
  "size": 24576,
  "contentType": "image/png",
  "url": "https://files.example.com/logos/logo.png"
}

delete

files.deleteDELETE/v1/buckets/{id}/files/{path}

files.delete(bucketId: string, path: string): Promise<WriteResponse<"file">>

Permanently deletes a file. There is no recycle bin — once the response returns, the underlying S3 object is gone. Throws NotFoundError if the file is already absent.

await client.files.delete(
  "bkt_01H8XYZABCDEFGHJKMNPQRSTVW",
  "logos/logo.png"
);

{
  "object": "file",
  "id": "fil_01H8XYZABCDEFGHJKMNPQRSTVW"
}