---
title: Overview
description: The full Files SDK API - ten unified methods plus a key-bound handle, the shared per-operation options, and the StoredFile return type.
---

The surface is small: a `Files` instance with ten methods, plus `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`](/api/upload) - write a body to a key, one or many.
- [`download`](/api/download) - read an object as a [`StoredFile`](/api/stored-file) or a stream.
- [`head`](/api/head) - fetch metadata without materializing the body.
- [`exists`](/api/exists) - check whether a key exists.
- [`delete`](/api/delete) - remove one object or many.
- [`copy`](/api/copy) - server-side copy with a read + write fallback.
- [`move`](/api/move) - rename a key, native where the provider supports it.
- [`list`](/api/list) - cursor-paginated listing, or `listAll` to walk every page.
- [`url`](/api/url) - a direct or signed URL to fetch a key.
- [`signedUploadUrl`](/api/signed-upload-url) - a presigned PUT/POST contract for direct browser uploads.
- [`file`](/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`](/api/transfer) - stream every object from one instance to another.
- [`sync`](/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](/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`, `url`) but rejects writes (`upload`, `delete`, `copy`, `move`, `signedUploadUrl`) with `FilesError { code: "ReadOnly" }`.

## Per-operation options

Every method accepts `signal`, `timeout`, and `retries`. 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: s3({ 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](/timeouts), [Retries](/retries), and [Cancellation](/cancellations) for how each behaves, and [Hooks](/usage#hooks) to observe operations as they run.

## The StoredFile type

`download`, `head`, and `list` all return [`StoredFile`](/api/stored-file) — a type that mirrors native `File`'s shape and adds the `key`, `etag`, and `metadata` that storage carries.