# Upload and download files (/build/files-upload-download)

Upload a file's bytes, make the item that names them, download them, hand out a link that expires, and replace them.



A file is two parts: a blob, the bytes, and a file item that names the blob by its hash and carries the title and everything else. Upload the bytes, then create the item. [Files](/build/files) explains why the two are apart.

To upload, your key needs write on a type outside `system.*`, or `blobs.manage`, and to create the item, write on its type. In the TypeScript examples, `marfa` is a client made as [the TypeScript SDK](/reference/typescript-sdk#create-a-client) shows. In the Swift examples, `copy` is an [open working copy](/reference/swift-sdk/working-copy#open-a-copy).

## Upload the bytes [#upload-the-bytes]

[Upload a blob](/reference/api/blobs/uploadBlob) takes the bytes as the request body, **as they are rather than as a form**, with their media type as the `Content-Type`. Marfa answers the blob's `hash`, `mime_type` and `size_bytes`. **The hash comes from your file's own bytes:** wherever a later step shows `<hash>`, use the one your upload returned.



**CLI**

```bash  
marfa blobs upload reading-list.txt
```

**HTTP**

```http
POST /blobs
Authorization: Bearer <key>
Content-Type: text/plain

<the bytes of reading-list.txt>
```

**TypeScript**

```ts
import { readFile } from "node:fs/promises";

const { data: blob, error } = await marfa.POST("/blobs", {
  body: await readFile("reading-list.txt"),
  headers: { "Content-Type": "text/plain" },
});
if (error) throw new Error(error.error.message);
```

**Swift**

```swift
let upload = try await copy.blobs.put(file: fileURL, mimeType: "text/plain")
guard let hash = upload.blob else { return }
```

The same bytes always give the same hash, so uploading them again **stores nothing more**. An upload has no size cap: Marfa ends one only when no bytes arrive for 60 seconds.

## Point an item at the bytes [#point-an-item-at-the-bytes]

Create a file item whose **`blob_ref`** is the hash the upload returned. `core.file` takes any file, and `core.file.image`, `core.file.audio`, `core.file.video` and `core.file.webpage` fit their kinds.



**CLI**

```bash  
marfa items create --type core.file --prop title=reading-list.txt \
  --prop blob_ref=<hash> \
  --prop mime_type=text/plain
```

**HTTP**

```http
POST /items
Authorization: Bearer <key>
Content-Type: application/json

{
  "type": "core.file",
  "properties": {
    "title": "reading-list.txt",
    "blob_ref": "<hash>",
    "mime_type": "text/plain"
  }
}
```

**TypeScript**

```ts
const { data: created } = await marfa.POST("/items", {
  body: {
    type: "core.file",
    properties: { title: "reading-list.txt", blob_ref: blob.hash, mime_type: blob.mime_type },
  },
});
```

**Swift**

```swift
_ = try await copy.items.create(Draft(
    type: "core.file",
    properties: ["title": "reading-list.txt", "blob_ref": .string(hash), "mime_type": "text/plain"]))
_ = try await copy.drain()
```

In Swift, `put` and `create` only queue: **drain the queue** before another client reads the blob or the item. `marfa items add reading-list.txt` uploads and creates in one command. A housekeeping job then reads the bytes and adds what the item lacks, such as `extracted_text`, so [a search](/build/list-filter-search#search) finds the file by its words.

**Until an item names the hash, the bytes can't be read**, even with the key that uploaded them. A file item may name only bytes its writer uploaded or can already read, so upload with **the same key** that writes the item: any other hash is refused `404 blob_not_found`.

## Attach a file to a note or another item [#attach-a-file-to-a-note-or-another-item]

To attach a file to a note or any other item, link them with an `attached-to` edge from the file item, as `marfa items attach <id> photo.jpg` does in one command. The file is then an **attachment**: it goes to the bin with the last item it's attached to, and comes back with any of them ([Edges](/build/edges)). A synced folder does it from the note's [`has-attachment` line](/use/work-with-folder-files#attach-a-file-to-a-note).

## Download the bytes [#download-the-bytes]

[Download a blob](/reference/api/blobs/downloadBlob) answers the bytes as they were uploaded. Marfa sends them as an attachment named after the hash, so take the file's name from the item's **`title`**, and **write to a path other than the file you uploaded**: `--output` and `writeFile` replace what is there. A `Range` header such as `bytes=0-1023` gets part of a blob.



**CLI**

```bash  
marfa blobs download <hash> --output reading-list-downloaded.txt
```

**HTTP**

```http
GET /blobs/<hash>
Authorization: Bearer <key>
```

**TypeScript**

```ts
import { writeFile } from "node:fs/promises";

const { data: bytes } = await marfa.GET("/blobs/{hash}", {
  params: { path: { hash: blob.hash } },
  parseAs: "arrayBuffer",
});
await writeFile("reading-list-downloaded.txt", Buffer.from(bytes!));
```

**Swift**

```swift
let bytes = try await copy.blobs.withFile(hash) { url in try Data(contentsOf: url) }
```

A blob you may not read answers `404 blob_not_found`, like a missing one, and `503 blob_store_unavailable` means try again later. In Swift, read the file inside the closure, because the copy can remove it afterward ([Keep files in a working copy](/build/keep-files-in-a-working-copy)).

## Hand out a time-limited link [#hand-out-a-time-limited-link]

An image element in a web page can't send your key. [Get a blob URL](/reference/api/blobs/getBlobUrl) answers a link that serves the bytes to anyone who has it. `ttl_seconds` is **an hour by default, and at most seven days**:



**CLI**

```bash  
marfa blobs url <hash> --ttl-seconds 900
```

**HTTP**

```http
GET /blobs/<hash>/url?ttl_seconds=900
Authorization: Bearer <key>
```

**TypeScript**

```ts
const { data: link } = await marfa.GET("/blobs/{hash}/url", {
  params: { path: { hash: blob.hash }, query: { ttl_seconds: 900 } },
});
```

Marfa checks your read **when it makes the link**, so revoking your key doesn't end a link early. Ask for a link when you need one, with the shortest lifetime that serves, and **don't store it**.

## Replace a file's bytes [#replace-a-files-bytes]

Upload the replacement, then update the file item's `blob_ref` to the hash that upload returned, **naming the version you read**, as [Update items without losing changes](/build/write-safely) shows:

```bash
marfa blobs upload reading-list.txt
marfa items update <id> --version <version> --prop blob_ref=<new-hash>
```

Marfa clears what it read from the old bytes, such as `extracted_text`, unless the same write names it, and reads the new bytes. The old blob stays **as long as an earlier version** of the item names it.

The rules are in the [blobs](https://github.com/withmarfa/marfa/blob/main/conformance/spec/blobs.md) chapter of the contract.
