MyJackfruit

Help
Browse topics · Vaults and access by API

Vaults and access by API

← Vaults and access by API

How do I create a vault, list vaults and export one by API?

Short answer

Create a vault with POST /base/vault/create-named, list your vaults with GET /lws/vaults, and take a copy with POST /base/vault/export/archive.

Before you start

A sign-in token for a person who already has a vault; for a copy, Control on 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. Create a vault.

    Send name, the new vault's name, and represents, the full GilbVeda type address of what it holds, to the identity host:
    POST https://id.gilb.com/base/vault/create-named

    More about this

    For a person's vault, represents is https://veda.gilb.com/base/t/Person; left out, the answer is 400. To make it inside a vault you own, add parentVault, that vault's @id from GET https://id.gilb.com/lws/vaults; one you do not own answers 403. The answer is 201 with vault, vaultId, name, parent, represents, and status live; 202 with status partial means: send the same request again. A name that is taken or reserved answers 400 with the reason. This makes an additional vault; a person's first vault is made at sign-in, as the Developer Guide's chapter Dev.Guide.GetStarted shows.

  2. List the vaults the person can reach.

    Send the request with the person's token and a new proof:
    GET https://id.gilb.com/lws/vaults

    More about this

    Each entry has vaultId, the vault address to use in other calls, as given; it may end in /vault or /base. It also has @id, name, represents, partOf, modes, what the person may do there, and isLandingVault, true for the vault they sign in to. With no token the answer is 200 with an empty list, not 401, so an empty list can mean the call was not signed in.

  3. Take a copy of a vault.

    Send vaultId, the vault's id, to the vault's own host, and save the answer as a file:
    POST https://<name>.gilb.com/base/vault/export/archive

    More about this

    The answer is 200 with a .tar file, a file that packs many files together: manifest.json, a list of everything in the copy; datoms.json, the facts of every record; and the folder blobs, with the stored files, also files removed from the vault. It holds the records as they are now, not deleted records or earlier versions. The headers x-base-export-files, x-base-export-blobs and x-base-export-facts give the counts. Read and Write without Control get 403; no token gets 401. If the records and files do not agree, the answer is 409 before any byte; a file that stops early failed midway. POST /base/vault/export gives the facts alone, as JSON.

Deeper

Also asked:

Can my app delete a vault by API? Not offered to apps: the Developer Guide has no call for it. If you need this, write to [email protected].

Every call carries the header Authorization: DPoP followed by the token, and a new DPoP proof. A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449).

Send a new vault to https://id.gilb.com; the Developer Guide lists 404 for one sent to a vault's own host. A program signed in as itself, with its own token, cannot create a vault: 403 A machine credential cannot mint a vault — the vault owner mints VaultAI.

A vault name is used once on GilbPlatform, and names GilbPlatform keeps for itself, such as kaizen, veda, id and support, are reserved; the answer on system vaults says more.

Whoever creates a vault holds Control on it. Control gives no Read or Write by itself, but whoever holds it can take a copy of the whole vault, every record and file, and can give themselves Read or Write.

The Developer Guide, GilbPlatform's guide for people who build apps on it, shows the list in its chapter Dev.Guide.GetStarted, https://appbuilder.gilb.com/base/e/06gkzpwfthtgf9py7m3qd5dx50, and the copy 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. It checked the list and the refusals of a copy on production; a finished copy and create-named are from GilbPlatform's code.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/vault.ts:104-115 (create-named body: name 1-63, parentVault, represents), :365-418 (POST /base/vault/create-named: authenticated caller, 401 without a token), :906-917 (POST /base/vault/export: Control, JSON), :919-951 (POST /base/vault/export/archive: Control; application/x-tar; x-base-export-files, -blobs, -facts; 409 before any byte; a mid-stream failure truncates), :216-238 (export = current state; archive = data and files, live and ended; 403 without Control), :674-711 (vault delete and restore: owner or operator only, requireOwnerOrOperator); src/auth/create-named-vault.ts:84 (A machine credential cannot mint a vault — the vault owner mints VaultAI), :106-124 (a person must own the parent), :163-191 (represents decided first; omitted or non-resolving → 400, represents is the full GilbVeda type IRI …), :281-314 and :540-580 (parentVault not a known vault entity → 400, lines 287 and 554; not yours → 403), :466-520 (201 live / 202 partial, line 471; body vault, vaultId, name, parent, represents, created, status; partial: re-issue the identical request, line 516), :650-660 (reserved, taken → 400 {error}, line 653). GilbApp ebd9415e (live at https://gilb.com/app/version.json, read 2026-11-11): src/lib/base/vaultSets.ts:200-208 (entity = the /lws/vaults @id), src/components/CreateVaultDialog.tsx:110-123, :207 (parentVault = that entity), src/lib/base/config.ts:711-718 (archive asked of the vault's own origin). Dev.Guide.GetStarted (A 06gkzpwfthtgf9py7m3qd5dx50, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Token (first vault through verify-code with name; create-named is for an additional vault), FindVault (entries, vaultId /vault or /base, no token → 200 empty; verified 2026-10-15). Dev.Guide.Files (A 06gkzpww3sseh5eskg4h42ts5g, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Export (control needed; refusals verified 2026-10-15; success not yet verified). Dev.Guide.Errors (A 06gkzpwxmnxf90zcc3mzc757xg, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Answer25 (404 when sent to a vault host; not yet verified). Shared with vaults/how-do-i-download-a-copy-of-my-vault (what the copy holds, the three parts, 409/no copy with gaps), vaults/what-are-system-vaults-and-why-cant-i-make-one (reserved names), vaults/who-can-give-access-and-to-whom (whoever makes a vault holds Control). Rows: Developer.CreateVaultByApi, ListReachableVaultsByApi, VaultArchiveExportByApi.

For developers

curl

create-vault.sh

# Make an additional vault for the signed-in person.
curl -s https://id.gilb.com/base/vault/create-named \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://id.gilb.com/base/vault/create-named>" \
  -H "Content-Type: application/json" \
  -d '{"name":"<new vault name>","represents":"https://veda.gilb.com/base/t/Person"}'
# 201: {"vault":"...","vaultId":"...","name":"<new vault name>","parent":null,"represents":"https://veda.gilb.com/base/t/Person","created":true,"status":"live"}

curl

list-vaults.sh

# Which vaults can the signed-in person reach?
curl -s https://id.gilb.com/lws/vaults \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://id.gilb.com/lws/vaults>"

curl

copy-vault.sh

# Take a full copy (records and files) of a vault. Needs Control on it.
curl -s https://<name>.gilb.com/base/vault/export/archive \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://<name>.gilb.com/base/vault/export/archive>" \
  -H "Content-Type: application/json" \
  -d '{"vaultId":"https://<name>.gilb.com/vault"}' \
  -o vault-copy.tar

Checked against GilbApp d529620.