---
title: API reference
description: The full Files SDK API - eleven unified methods plus abortUpload and a key-bound handle, the shared per-operation options, and the FileInfo and StoredFile result types.
---

The surface is small: a `Files` instance with eleven methods, plus `files.abortUpload()` to discard a persisted resumable upload and `files.file(key)` for a key-bound handle. Each method takes one key (or an array, where bulk applies), accepts the shared `signal` / `timeout` / `retries` options, and throws a normalized `FilesError`. Each method has its own page; this page covers the pieces that cut across all of them.

## Functions

- [`upload`](/docs/api/upload) - write a body to a key, one or many.
- [`download`](/docs/api/download) - read an object as a buffered or streamed [`StoredFile`](/docs/api/stored-file).
- [`head`](/docs/api/head) - fetch metadata without materializing the body.
- [`exists`](/docs/api/exists) - check whether a key exists.
- [`delete`](/docs/api/delete) - remove one object or many.
- [`copy`](/docs/api/copy) - server-side copy with a read + write fallback.
- [`move`](/docs/api/move) - rename a key, native where the provider supports it.
- [`list`](/docs/api/list) - cursor-paginated listing, or `listAll` to walk every page.
- [`search`](/docs/api/search) - glob/regex/substring key search over every page.
- [`url`](/docs/api/url) - a direct or signed URL to fetch a key.
- [`signedUploadUrl`](/docs/api/signed-upload-url) - a presigned PUT/POST contract for direct browser uploads.
- [`abortUpload`](/docs/resumable#discarding-a-persisted-session) - discard a persisted resumable upload from its session token.
- [`file`](/docs/api/file) - a `FileHandle` bound to one key.

Two **global functions** stand apart from the instance methods — they take two `Files` instances and move objects between backends, built entirely on the methods above:

- [`transfer`](/docs/api/transfer) - stream every object from one instance to another.
- [`sync`](/docs/api/sync) - mirror one instance onto another (skip-unchanged, prune, dry-run).

## Scoping keys with a prefix

Pass `prefix` to the constructor and every key is resolved relative to it — prepended on the way in, stripped on the way out — so application code works in its own namespace. See [Prefixes](/docs/prefixes) for the full behavior, including slash normalization and how `list()` scopes to a path boundary.

## Read-only instances

Pass `readonly: true` to `new Files(...)`, or call `files.readonly()`, to create a view that still allows reads (`download`, `head`, `exists`, `list`, `listAll`, `search`, `url`) but rejects writes (`upload`, `delete`, `copy`, `move`, `signedUploadUrl`, `abortUpload`) with `FilesError { code: "ReadOnly" }`. See [Read-only](/docs/readonly) for the full behavior.

## Per-operation options

Every single-key call (plus `list`, `listAll`, and `search`) accepts `signal`, `timeout`, and `retries`; the array forms take `concurrency` / `stopOnError` instead (see [Bulk actions](/docs/bulk)). Set them once on the constructor as defaults, then override per call - a per-call value wins over the constructor default for that operation.

```ts lineNumbers
const files = new Files({
  adapter: r2({ bucket: "uploads" }),
  timeout: 10_000, // default per-attempt timeout for every call
  retries: { max: 3, backoff: ({ attempt }) => attempt * 500 },
});

// A per-call value wins over the constructor default.
await files.head("avatars/abc.png", { timeout: 2_000 });
```

<AutoTypeTable
  path="../../packages/files-sdk/src/index.ts"
  name="OperationOptions"
/>

See [Timeouts](/docs/timeouts), [Retries](/docs/retries), and [Cancellation](/docs/cancellations) for how each behaves, and [Hooks](/docs/usage#hooks) to observe operations as they run.

## The FileInfo and StoredFile types

`head`, `list`, `search`, and `upload` return [`FileInfo`](/docs/api/stored-file): an object's `key`, `size`, `contentType`, `etag`, `lastModified`, and `metadata`, with no body. `download` returns a [`StoredFile`](/docs/api/stored-file): the same fields plus native `File`'s `name` / `type` and the body accessors.