MyJackfruit

Help
Browse topics · Files

Files

← Back to How does a profile picture (face) work?

How do I upload, download and end files?

Short answer

Upload raw bytes to /lws/vault/<encoded vault id>/files?name=<file name>, download them from /files/<id>, and end a file with DELETE.

Before you start

Your app holds a person's sign-in token and its key, and the person may write to the vault.

Words used here (2)
sign-in token
A sign-in token is the credential GilbPlatform issues when a person signs in; your app presents it, with a proof, on each request.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
Steps
  1. Upload the file's bytes into the vault.

    Send POST https://<name>.gilb.com/lws/vault/<the vaultId, encoded>/files?name=<file name> with Content-Type set to the file's type and the file's bytes as the body; the answer is 201 with location, /files/<id>.

    More about this

    Send the bytes as they are, not as a form. The body of the answer has entity, the address of the record that describes the file, contentHash, the SHA-256 fingerprint of the bytes, 64 hex characters, byteSize and created. Add folder= and tag= as often as you like. The same bytes in one vault are kept once. The same person sending the same file with the same details again gets 200 and created false; another person gets 201 and a record of their own. You can read back what you upload.

  2. Download the bytes from /files/<id>.

    Send GET https://<name>.gilb.com/files/<id> with the token; the answer is 200 with the bytes, the stored Content-Type and the ETag, the file's version tag, sha256:<contentHash>.

    More about this

    A Range header, such as bytes=0-1023, answers 206 with that part and Content-Range; a range the file cannot meet answers 416. HEAD gives the same headers with no body. A file you may not read answers 404. A plain Bearer token, one bound to no key, works here too instead of the DPoP token, which carries a short signed note for each request: /lws, /files and many /base routes, such as /base/search, take it with no proof; the routes that sign in, trade tokens, register an app or run the AI chat do not.

  3. End the file with DELETE.

    Send DELETE https://<name>.gilb.com/files/<id>; the answer is 204, and the file is kept, not erased.

    More about this

    The bytes are still served at /files/<id>, the record that describes the file gains fileLifecycleState ended, and the vault's list of files no longer shows it, unless the list is asked for with lifecycle=ended or lifecycle=all. Ending it again answers 204 again. If-Match is ignored here. An ended file is still in a full copy of the vault. Someone who may read the file but not write it gets 403.

Deeper

Also asked:

How do I upload, download and delete a file by API? Upload the bytes with POST /lws/vault/<encoded vault id>/files?name=<file name>, download them with GET /files/<id>, and end the file with DELETE /files/<id>; an ended file is kept, not erased.

How do I attach an uploaded file to a record by API? Name the record when you upload: add storedWith=<the record's address, as GilbPlatform gave it> to the upload address. The file's record then holds a:fileStoredWith, and GilbApp lists the file under ATTACHMENTS.

A file's record has an address of its own, entity in the upload answer, such as https://<name>.gilb.com/vault/e/<id>. A GET of that address, with a DPoP token, answers 303 and sends you on to /files/<id>; to read the record, the file's name, type, size, folders and tags, ask for it with Accept: application/json or application/ld+json.

Other refusals of an upload. A form body, multipart, answers 415. No body, no name, two names, a malformed Content-Type, or a folder or tag the platform cannot use answer 400. ?thumbnail=whole asks for a small copy of a picture, a separate file you end yourself; with a format the platform cannot make small, such as HEIC, the answer is 415 and nothing is stored, and a JPEG sent with ?thumbnail=whole that carries more than 16 MB of metadata answers 413. ?thumbnail=whole together with ?face= answers 400. Someone who may not write the vault gets 403, and a bad token 401.

POST /files?name=<file name>, with no vault in the address, puts the file in your own vault instead. A piece-by-piece upload for large files, under /lws/vault/<encoded vault id>/file-uploads, is not covered here.

The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.Files, https://appbuilder.gilb.com/base/e/06gkzpww3sseh5eskg4h42ts5g. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/routes/files.ts:1300-1369 (registerFileRoutes: nosniff on every answer; raw stream parser; GET /files/:id; POST/PUT /files; POST/PUT /lws/vault/:vaultId/files; piece uploads /lws/vault/:vaultId/file-uploads :1336-1351; DELETE /files/:id), :23-77 (header: per-vault dedupe; same principal 200 created:false, another principal 201; DELETE = END), :94-95 (Bearer floor on the file surface), :309 (16 MB JPEG metadata cap, with ?thumbnail=whole only, :505-516), :340-591 (streamStoreUpload: 415 multipart PUT/POST takes the raw file bytes … :373-380; 400 malformed Content-Type, Exactly one non-empty ?name= is required, folder grammar :381-399; ?face= empty, ?thumbnail= only whole, ?fileType= only with it :416-466; face and thumbnail together 400 :428-435; 415 "?thumbnail=whole needs a picture the server can make small (JPEG, PNG, WebP, AVIF, GIF or TIFF) … Nothing was stored." :473-479; no body 400 :487-491; 201/200 :568-588; Location /files/<id>; body entity, contentHash, byteSize, created), :600-640 (POST /files: the writer's own vault), :642-715 (vault-targeted upload, resolveVaultTarget write: 403/400), :717-807 (DELETE: identical 404 for an unreadable file; endFile; 204, also when already ended; no If-Match read), :870-985 (download: 404, 416 + Content-Range, ETag sha256:<hash>, Content-Type, 206 + Content-Range, HEAD); src/files/file-store.ts:291-303 (TagStringRefusedError 400), :359-373 (the uploader's self-read grant); src/routes/file-browse.ts:91-97 (ended files hidden unless lifecycle=ended or all); src/files/file-vocab.ts:160-167 (fileContentUrlFor https://<host>/files/<id>); src/routes/read.ts:287-306 (GET /base/e/:id of a file: 303 unless Accept names application/ld+json or application/json), :866-881 (asksForDescription); src/write/ingest.ts:1829-1840 (the self-read carve-out on the create). Production, no token, https://appbuilder.gilb.com/files/zzzz 2026-11-11: 404. GilbVeda t:FileContentHash (The SHA-256 of a file's content (64 lowercase hex chars), Suggested), t:FileLifecycleState (ABSENCE MEANS LIVE), public terms search 2026-11-11. Dev.Guide.Files (A 06gkzpww3sseh5eskg4h42ts5g, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Files.Upload (verified 2026-10-15), .Read, .End (The bytes are kept, ignores If-Match, ending again 204), .Thumbnail, .Browse, .Export (an export includes ended files). The code example is written here, placeholders only. Rows: Developer.FileUploadByApi, FileDownloadByApi, FileEndByApi, FileEntityRedirect, FileUploadRefusals.

For developers

curl

files.sh

# Upload a picture into a vault: the raw bytes, not a form.
curl -i -X POST "https://<name>.gilb.com/lws/vault/<encoded vault id>/files?name=<file name>" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for this POST and this address>" \
  -H "content-type: image/jpeg" \
  --data-binary "@<path to the file>"
# 201, location: /files/<id>, {"entity":"https://<name>.gilb.com/vault/e/<id>","contentHash":"...","byteSize":...,"created":true}

# Download the first 1024 bytes.
curl -s "https://<name>.gilb.com/files/<id>" -H "Range: bytes=0-1023" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for this GET and this address>" \
  -o "<file name>.part"

# End the file: kept, not erased. 204.
curl -i -X DELETE "https://<name>.gilb.com/files/<id>" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for this DELETE and this address>"

Checked against GilbApp d529620.