How do I create a record in a vault?
Short answer
Get the vault's id, send the record's type and facts to /lws/vault/<encoded vault id>/c on the vault's host, and keep location.
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 (5)
- record's type
- A record's type says what kind of thing a record is, such as a note, a task or a person, taken from GilbVeda.
- 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.
- agent
- An agent is your AI following one written procedure, its standing instructions, for one kind of work.
- record's address
- A record's address is the web address that names one record for good: it never changes and is never given to another record.
Steps
Get the vault's id.
Send GET https://id.gilb.com/lws/vaults with the token and a new DPoP proof, and take the vaultId of a vault whose modes include write.
More about this
A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). A vault is the place where a person or a group keeps their records, and every record lives in exactly one vault. This create puts the record only in the vault its address names; it never falls back to another vault. Use vaultId as given; it can end in /vault or in /base, so do not build it yourself.
Send the record's type and facts to the vault's host.
Send POST https://<name>.gilb.com/lws/vault/<the vaultId, encoded>/c with a JSON body such as {type:t:Note,facts:{a:title:<a title>}}; the answer is 201.
More about this
Encoded means written with encodeURIComponent, so the address fits in one part of the path. type and the fact names come from GilbVeda, the shared list of terms; a record with no type reads back as t:UntypedEntity. The body may hold type, facts and agent and nothing else; any other key answers 400. No facts key answers 400; facts:{} makes an empty record, so do not rely on it. Every create makes a new record, even with the same body: to retry one safely, see the answer on making writes safe to retry.
Keep the address and ETag from the answer.
Store the record's address from the location header, and the ETag header.
More about this
The address names the vault's host, such as https://<name>.gilb.com/lws/r/<record id>; read, change and end the record there. An ETag is a fingerprint of the record's current state. You send it in If-Match when you change the record. The id is made by the platform; treat it as an opaque string and never read a time, an order or a meaning from it.
Deeper
Also asked:
How do I create a record by API? Send POST https://<name>.gilb.com/lws/vault/<the vaultId, encoded>/c with a JSON body such as {type:t:Note,facts:{a:title:<a title>}}; the answer is 201, with the record's address in location.
A vault name in place of the encoded vaultId answers 400 vault_name_unresolved, and a vault you may not write answers 403 vault target denied, with nothing written. Send the create to the vault's own host: the same request to https://id.gilb.com answers 403 too.
To make the vault owner's own card, the card a person keeps about themselves on GilbPlatform, send the same body to POST https://<name>.gilb.com/lws/vault/<the vaultId, encoded>/selfcard instead. If the vault has no own card yet, the call makes it: 201. Every later call returns the card already there, unchanged, with 200, so a retry never makes a second card and never changes the first; change its facts with PATCH. If the vault already holds several older own cards and nothing says which is the owner's, or the platform cannot read that, the answer is 409 SelfCardIdentityUnknown and nothing is made.
Two older doors create a record without naming a vault: POST /lws/c/<id> and POST /base/ingest put it in your own vault, whatever the address says; the id in /lws/c/<id> is not used. POST /base/ingest also matches a record that already holds exactly the same facts instead of making a new one. Use /lws/vault/<encoded vault id>/c, which puts the record where you say.
The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapters Dev.Guide.Writing, https://appbuilder.gilb.com/base/e/06gkzpwmgnzph1fb6jp7gf87c0, and Dev.Guide.GetStarted, https://appbuilder.gilb.com/base/e/06gkzpwfthtgf9py7m3qd5dx50. 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/lws/routes.ts:782-787 (GET /lws/vaults), :838-878 (POST /lws/vault/:vaultId/c; the vault from the path, :843-848 no fallback vault; Stamp the create INTO the named, authorized vault), :1156-1166 (lwsCreateBodySchema: required facts; type, facts, agent; additionalProperties false, refused because src/server/app.ts:340-341 sets removeAdditional false), :880-926 (POST /lws/vault/:vaultId/selfcard; 409 SelfCardIdentityUnknown :911-918), :979-997 (POST /lws/c/:id: writeTargetVaultForRequirer, the :id is not read), :349-375 (Location, ETag), :109-111 (strong sha256:<hex> ETag); src/lws/uri.ts:55-66 (Location on the vault's host); src/lws/crud.ts:102-110 and :193-199 (the id = an optional Slug prefix + uuidv7 in base32, so time-ordered: hence never read a time, an order or a meaning from it), :182-280 (lwsCreate: a new id every time; a:lwsSelf stamp :232-236, so facts {} still makes a record), :74-80 (default t:UntypedEntity); src/lws/self-card.ts:17-24 (An existing card is returned UNTOUCHED. Zero facts written; Field edits keep going through the existing PATCH route), :64-140 (201 created, 200 adopted or existing); src/baseconnect/self-card-address.ts:64, :100-120 (pointer read failed), :283-298 (one legacy card or a pointer: adopt; several legacy self-cards and no pointer: refuse); src/routes/write.ts:107-140 (POST /base/ingest: writer's own vault, mint-or-match by identity); src/auth/vault-provision.ts:1012 (own vault); src/authz/vault-target.ts:126-133 (no vault named: refused), :186-200 (400 vault_name_unresolved), :304-325 (403 vault target denied); src/lws/vaults.ts:563-610, :692 (vaultId and modes). Dev.Guide.Writing (A 06gkzpwmgnzph1fb6jp7gf87c0, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied); Dev.Guide.GetStarted (A 06gkzpwfthtgf9py7m3qd5dx50, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Writing.Create, .FactsKey (facts: {}: 201 and an empty record, Do not rely on it, verified 2026-10-15); GetStarted.FindVault, .Create; Addresses.Encoded, .Ids, .Host (403 through id.gilb.com, verified 2026-10-15); Errors.Answer03. Not followed: docs §7.2 ids are 12 CSPRNG characters (the ingest minter, not this door; see the report). The online card gloss is the one used on people/how-do-i-connect-a-card-to-the-persons-own-online-card (the card a person keeps about themselves on GilbPlatform); GilbVeda t:VaultSelfCard (Suggested, public terms search 2026-11-11). The code example is written here from the route at 498d29a0, placeholders only. Rows: GilbPlatform.RecordCreateInVault, Developer.ContainerListAndCreate, EnsureOwnCard.
For developers
curl
create-record.sh
# Create a note in a vault, on the vault's own host. <encoded vault id> = encodeURIComponent(vaultId).
curl -i -X POST "https://<name>.gilb.com/lws/vault/<encoded vault id>/c" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for this POST and this address>" \
-H "content-type: application/json" \
-d '{"type":"t:Note","facts":{"a:title":"<a title>"}}'
# 201, location: https://<name>.gilb.com/lws/r/<record id>, etag: "sha256:..."
Checked against GilbApp d529620.