MyJackfruit

Help
Browse topics · For developers

For developers

← For developers

How does a profile picture (face) work?

Short answer

Upload the photo with ?face=, keep the face file the answer names in leanFace, and set a:profilePhoto on the owner's own card to it.

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 (6)
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.
GilbPlatform
GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
field
A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
GilbApp
GilbApp is the app, opened in a web browser at https://gilb.com/app, where you open, fill and share your vaults.
sharing level
A sharing level says who may see one thing you share in MyNet, from Public, for everyone, to Private, for you alone.
Steps
  1. Upload the photo with ?face=.

    Upload the photo's bytes as any file, adding face=whole for the whole picture or face=<x>,<y>,<width>,<height> for the part the person marked:
    POST https://<name>.gilb.com/lws/vault/<vault id, encoded>/files?name=<file name>&face=whole

    More about this

    The four numbers are fractions of the picture, from 0 to 1, measured from its top left as the person sees it, the right way up; a box that runs past an edge is cut at the edge. Content-Type is the photo's type, such as image/jpeg or image/heic. The photo itself is stored first, whole and unchanged, and stays in the vault; then GilbPlatform makes the face, a second, small file. Encoded means written with encodeURIComponent, so the address fits in one part of the path. The answer on uploading, downloading and ending files shows the rest of an upload.

  2. Read leanFace in the answer.

    In the answer, read leanFace: kind stored gives the face file's entity and id; skipped or failed means no face was made, and detail says why.

    More about this

    A face is a JPEG at most 256 pixels on its longest side, made to be about 15 KB and never over 30 KB. Its name is the photo's with -face.jpg, and it gets the photo's folders and tags. cropped is true when a box was used. linkedToMaster true means the face carries a:croppedFrom, a link to the larger picture it was cut from; it is false when the face is no smaller. skipped with reason already-lean means the photo, with no box, is already at most 256 pixels and 15 KB; not-an-image means GilbPlatform cannot read that kind of file; failed means it tried and could not. In all three, the photo is stored all the same; only with already-lean is it small enough to serve as the face as it is.

  3. Set a:profilePhoto on the owner's own card.

    Write a:profilePhoto on the vault owner's own card, the card a person keeps about themselves on GilbPlatform, as the text /files/<the face's id>.

    More about this

    POST https://<name>.gilb.com/lws/vault/<vault id, encoded>/selfcard makes that card and answers 201, or, when the vault already has one, returns it unchanged and answers 200, so a second call does not make another; the answer on creating a record in a vault shows how. Then send PATCH to the card's address with If-Match; the answer on writing a record and reading it back shows how. a:profilePhoto is a field of t:Person and holds text, not a link {@id}; GilbApp writes it the same way. An organisation's picture is its logo, a:logo, a link to the file. A new face is a new file: the earlier one stays until you end it.

  4. Show the face.

    Fetch the face with the person's token:
    GET https://<name>.gilb.com/files/<the face's id>

    More about this

    A file you may not read answers 404. The token goes in Authorization: DPoP with a new DPoP proof (a short signed note your app makes for one request, naming its method and address), or as a plain Bearer token: /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. Another person's face is not read this way: ask GET https://id.gilb.com/base/connect/profile-photo?principal=<their WebID>, with or without a token. A WebID is the web address that names a person on GilbPlatform. It gives the picture only when that person has placed their photo at a sharing level that admits the caller, and 404 to anyone else. An img tag cannot send a token, so fetch the bytes and show them from memory.

Deeper

Also asked:

How do I set someone's profile picture by API? With that person's own sign-in token: upload the photo to their vault with ?face=whole, then set a:profilePhoto on their own card to /files/<the face's id>. Steps 1 to 3 show how.

face= with nothing after it answers 400 "?face= is empty — send 'whole' for the whole picture, four fractions to crop, or omit it entirely for an ordinary file". A box that is not four numbers answers 400 "face rectangle must be 'x,y,width,height' as four fractions of the picture; got '<what you sent>'", and a width or height of 0 or less answers 400 too. face= together with thumbnail=whole answers 400 "Send ?face= (a profile photo) or ?thumbnail=whole (a picture for display), not both". These are checked before anything is stored. Every other refusal is that of any upload.

A photo from an iPhone, HEIC, gets a face too. GilbPlatform first makes a JPEG copy that a browser can show, named with -view.jpg and linked to the photo by a:transcodedFrom, and cuts the face from that copy; leanFace.viewable names the copy, and the face's a:croppedFrom points at it. Show that copy when the person marks the box, then send the photo again with the box: the same person sending the same file with the same details gets 200, created false, and a new face. The photo itself stays as it came. If GilbPlatform cannot open the HEIC, kind is failed.

Faces are made from JPEG, PNG, WebP, AVIF, GIF, TIFF, HEIC and HEIF pictures; a picture over 80 megapixels gives failed. A clear background becomes white. The photo, the copy and the face are ordinary files of the vault, each with its own record, and each is ended with DELETE like any other file.

Who else sees the face is set by the person, not by the file's address: knowing /files/<id> gives no one the picture, and the route in step 4 shows it to others only at the sharing level the person chose.

The Developer Guide, GilbPlatform's guide for people who build apps on it, does not cover the face yet. Its chapter Dev.Guide.Files, https://appbuilder.gilb.com/base/e/06gkzpww3sseh5eskg4h42ts5g, covers uploads. 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:259-300 (UploadQuery face: ?face=whole and ?face=x,y,w,h, both derive a lean face), :406-452 (blank ?face= 400 message; parseFaceRect 400; thumbnail with face 400 message; all before a byte is consumed), :540-590 (master stored first, then deriveAndStoreLeanFace; ack carries leanFace only when asked), :1320-1386 (GET/POST/PUT /files, POST /lws/vault/:vaultId/files); src/files/lean-face.ts:95-104 (FaceRect fractions 0..1), :172-184 (skip reasons not-an-image, already-lean; LEAN_FACE_MAX_EDGE 256, TARGET 15,000 B, CEILING 30,000 B), :196 (image/jpeg), :209-215 (quality and edge ladders, MIN_EDGE 96), :233 (MAX_SOURCE_PIXELS 80,000,000, over it the deriver fails and the master is kept), :236-244 (decodable types), :285-325 (parseFaceRect messages; clamp into the picture), :420-452 (EXIF orientation applied first, display space; already-lean only with no rectangle, both edges <= 256 and bytes <= 15,000), :544 (flatten onto white); src/files/lean-face-store.ts:51-91 (outcome stored|skipped|failed, entity, id, width, height, cropped, linkedToMaster, viewable), :106-110 (-face.jpg), :127-260 (HEIC branch first; skip details; containment test, a:croppedFrom only when strictly smaller; tags and folders inherited; failures reported, never thrown), :286-420 (HEIC: viewable JPEG -view.jpg with a:transcodedFrom, face cut from it, a:croppedFrom to the copy, viewable in the reply), :427-431; src/files/heic-transcode.ts:1-60 (out-of-process decode, original never touched); src/files/file-vocab.ts:40-75 (a:croppedFrom on the picture, a:profilePhoto stays one scalar pointing at the lean face); src/lws/routes.ts:878-920 (POST /lws/vault/:vaultId/selfcard); src/routes/connect-profile-fields.ts:312-410 (GET /base/connect/profile-photo?principal=: bytes only when a profile-photo claim admits the viewer; "An unguessable /files/<id> is NOT access control (file entity is owner-only via a:directReader)"; 404 non-disclosure). GilbApp ebd9415e (live at https://gilb.com/app/version.json, read 2026-11-11): src/lib/base/vaultProfilePhoto.ts:1-14 (display: authenticated GET /files/<id>, bare <img> cannot carry Bearer; write: file bytes, then Person a:profilePhoto), :880-940 (upload with face, photoRef = /files/<face or master id>, the face is the lean file when there is one, else the master), :543, :611 (patchRecord a:profilePhoto = /files/<id> text), :1000-1008 (organisation logo a:logo as {@id}). GilbVeda (public read, 2026-11-11): a:profilePhoto (Approved; inline-literal:text; a:fieldOf Person; a:predicateAttribute a:profilePhoto|a:hasPhoto), a:croppedFrom (Suggested; reference-valued:@id), t:FaceCrop (Suggested). Public reads, no token, 2026-11-11: https://id.gilb.com/base/connect/profile-photo?principal=https%3A%2F%2Fkaizen.gilb.com%2Fi 404 {error:NotFound,message:No resource at profile-photo:https://kaizen.gilb.com/i}; with no principal 400 querystring must have required property 'principal'. Dev.Guide.Files (A 06gkzpww3sseh5eskg4h42ts5g, pack GilbPlatformDeveloperGuide, 2026-11-11): Upload, Read, Thumbnail; no face. Row: GilbPlatform.FileProfileFace.

For developers

curl

profile-face.sh

# 1. Upload the photo and ask for a face: here the part the person marked, as fractions of the picture.
#    face=whole asks for the whole picture, made small.
curl -s -X POST "https://<name>.gilb.com/lws/vault/<vault id, encoded>/files?name=<file name>&face=0.25,0.1,0.5,0.5" \
  -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 photo>"
# 201 {"entity":"https://<name>.gilb.com/vault/e/<photo id>", ... ,"created":true,
#      "leanFace":{"kind":"stored","entity":"https://<name>.gilb.com/vault/e/<face id>","id":"<face id>",
#                  "width":256,"height":256,"cropped":true,"linkedToMaster":true, ...}}

# 2. The owner's own card: 201 when made, 200 when the vault already had one (returned unchanged).
#    Keep location, the card's address, and ETag.
curl -s -i -X POST "https://<name>.gilb.com/lws/vault/<vault id, encoded>/selfcard" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for this POST and this address>" \
  -H "content-type: application/json" \
  --data '{"type":"t:Person","facts":{"a:name":"<their name>"}}'

# 3. Point the card at the face: a:profilePhoto is text, /files/<face id>, not a link.
curl -s -X PATCH "<the card's address>" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for this PATCH and this address>" \
  -H "content-type: application/merge-patch+json" \
  -H "If-Match: <the card's ETag>" \
  --data '{"a:profilePhoto":"/files/<face id>"}'

TypeScript

face-param.ts

// Turn the box a person drew on the picture they see into the face= value.
// The box and the picture size are in the same units, such as screen pixels.
export function faceParam(box: { left: number; top: number; width: number; height: number },
                          shown: { width: number; height: number }): string {
  const f = (n: number) => Math.min(Math.max(n, 0), 1).toFixed(4);
  if (box.width <= 0 || box.height <= 0) return "whole"; // nothing marked: use the whole picture
  return [box.left / shown.width, box.top / shown.height, box.width / shown.width, box.height / shown.height]
    .map(f)
    .join(",");
}

type LeanFace =
  | { kind: "stored"; id: string; entity: string; linkedToMaster: boolean; viewable?: { id: string } }
  | { kind: "skipped"; reason: "not-an-image" | "already-lean"; detail: string }
  | { kind: "failed"; detail: string };

// The /files/ address to write in a:profilePhoto: the face when one was made, else the photo itself.
export function profilePhotoValue(upload: { entity: string; leanFace?: LeanFace }): string {
  const lf = upload.leanFace;
  const id = lf?.kind === "stored" ? lf.id : upload.entity.slice(upload.entity.lastIndexOf("/") + 1);
  return `/files/${id}`;
}

Checked against GilbApp d529620.