Upload and download files
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 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 shows. In the Swift examples, copy is an open working copy.
Upload the bytes
Upload a blob 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.
marfa blobs upload reading-list.txtThe 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
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.
marfa items create --type core.file --prop title=reading-list.txt \
--prop blob_ref=<hash> \
--prop mime_type=text/plainIn 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 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
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). A synced folder does it from the note's has-attachment line.
Download the bytes
Download a blob 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.
marfa blobs download <hash> --output reading-list-downloaded.txtA 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).
Hand out a time-limited link
An image element in a web page can't send your key. Get a blob URL answers a link that serves the bytes to anyone who has it. ttl_seconds is an hour by default, and at most seven days:
marfa blobs url <hash> --ttl-seconds 900Marfa 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
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 shows:
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 chapter of the contract.