# How do I write a record and read it back?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

Find the vault's host, create the record there, read it back at the address in location, and change it with its ETag.

## Before you start

Your app holds [a person's sign-in token and the key it is bound to](http://support.gilb.com/help/how-do-i-use-the-sign-in-kit), and [the person may write to the vault](http://support.gilb.com/help/how-do-i-grant-access-by-api).

## Steps

1. Find the vault's id and host.

   Send GET https://id.gilb.com/lws/vaults with the token and [a new proof](http://support.gilb.com/help/how-do-i-make-a-dpop-proof-for-each-request), and take the vaultId of the vault you want; its host is the part between https:// and the next /, such as &lt;name\>.gilb.com.

   A vault is the place where a person or a group keeps their records. Every call here 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\). Use vaultId as given: it can end in /vault or in /base. Each entry also has modes, such as read and write. With no token the list answers 200 with no vaults, not 401.
2. Create the record on the vault's own host.

   Send POST https://&lt;name\>.gilb.com/lws/vault/&lt;the vaultId, encoded\>/c with a JSON body that holds type and facts; the answer is 201, with the record's address in location and an ETag.

   Encoded means written with encodeURIComponent, so the address fits in one part of the path. type is the kind of record, such as t:Note, and facts its facts, such as a:title; both names come from GilbVeda, the shared list of terms. The same create sent to https://id.gilb.com answers 403 "vault target denied", even when you may write the vault. [The answer on creating a record in a vault](http://support.gilb.com/help/how-do-i-create-a-record-in-a-vault) says more.
3. Read the record back at the address in location.

   Send GET to that address, with a new proof made for it; the answer is 200 with the record and an ETag.

   An ETag is a fingerprint of the record's current state. The address names the vault's host, such as https://&lt;name\>.gilb.com/lws/r/&lt;record id\>: use it as given. Fact names come back without a:, so a:title reads title, and a record made with no type reads back as t:UntypedEntity. 404 means the record is not there, you may not read it, or you asked on another host; the platform does not say which. The ETag reads W/"sha256:…": the W/ is added on the way when the answer is compressed, and it names the same state.
4. Change the record with the ETag you read.

   Send PATCH to the same address with Content-Type: application/merge-patch+json, If-Match set to the ETag, and a body of only the facts to change; the answer is 200 with the new ETag.

   A null value removes that fact. To replace the whole record, send PUT with If-Match and a body with type and facts: a fact you leave out is removed. 412 means someone changed the record after you read it, and nothing was written: read it again. [The answer on writing only if nothing changed](http://support.gilb.com/help/how-do-i-write-only-if-nothing-changed-if-match) says more.

## Deeper

Being allowed to write is not being allowed to read. Whoever makes a vault can read and write it, and access to write a whole vault gives read as well. An app with append access only, which may add to a vault but not read it, can add a:directReader, set to its own principal, the identity an access decision is recorded against, to a record it creates, and then read that record back. It can do so only when it creates the record, and only for itself; naming anyone else is refused with 403.

GilbPlatform has other ways to write. PUT https://&lt;name\>.gilb.com/base/e/&lt;record id\>, on a system vault's host, writes a whole record at an id you give, with type, facts and agent, and checks no If-Match. POST /base/ingest and POST /lws/c/&lt;id\> make a new record in your own vault, not in a vault you name. The create in step 2 is the one the Developer Guide uses, and the only one that puts the record in the vault you name.

GilbPlatform's own web apps send a plain Bearer token, bound to no key, instead of the DPoP 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. A token from the e-mail-code sign-in is bound to a key and always needs its proof.

The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapters Dev.Guide.GetStarted, https://appbuilder.gilb.com/base/e/06gkzpwfthtgf9py7m3qd5dx50, Dev.Guide.Writing, https://appbuilder.gilb.com/base/e/06gkzpwmgnzph1fb6jp7gf87c0, and Dev.Guide.Addresses, https://appbuilder.gilb.com/base/e/06gkzpwjzhtwb4m72ae1jy3t2c. 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, resolveVaultTarget mode write, "never a default"; 201 + Location + ETag via sendWriteResult :349-375, Location names the vault host the record was minted under, src/lws/uri.ts:55-66\), :585-597 and :152-220 \(GET /lws/r/:id: host-routed; identical 404 for absent, unreadable or another host; ETag; setReadCaching\), :109-111 \(strong "sha256:&lt;hex\>" ETag\), :1027-1074 \(PATCH, merge-patch parser :560-575, If-Match optional\), :999-1025 \(PUT, If-Match\), :1156-1166 \(body schema type, facts, agent; additionalProperties false, refused because src/server/app.ts:340-341 sets removeAdditional false\); src/lws/vaults.ts:563-610 \(no token: 200 with no vaults\), :692 \(modes\); src/lws/crud.ts:74-80 \(no type: t:UntypedEntity; fact names read back without a:\), :300-380 and :403-430 \(PUT: 428 without If-Match, 412 stale at :427, a fact left out is removed\), :459-560 \(PATCH: null removes a fact, 200 + new ETag\); src/authz/vault-target.ts:304-325 \(403 "vault target denied: the principal holds no write reach on vault …"\); src/write/ingest.ts:1815-1952 \(write gives no read: the self a:directReader carve-out, CREATE only, value exactly the writer's principal; anything else 403 WriteForbiddenError\); src/authz/authorize-read.ts:1-30 \(positive-grant read, no owner arm\); docs/BASE-DEVELOPER-GUIDE.md §5.6 :6020-6090 \(creator self-grant read+write; "WRITE never confers READ" :6072-6090\); src/routes/write.ts:20-136 \(PUT /base/e/:id: type, facts, agent, no If-Match read; entity and vault from the request host, :62-63; POST /base/ingest: own vault, mint-or-match\); src/uri/vault-segment.ts:321-461 \(on a person's vault host /base/e/... is refused; /vault/... is rewritten\); src/lws/routes.ts:979-997 \(POST /lws/c/:id: writeTargetVaultForRequirer, the id is not used\); src/auth/vault-provision.ts:1012 \(the writer's own vault\); src/auth/served-host.ts:105-115 \(the DPoP proof names the registered vault host\); the code at 498d29a0 shows only src/lws/crud.ts and src/lws/routes.ts read it. Public read, no token, 2026-11-11: https://id.gilb.com/lws/vaults 200 {"total":0,"vaults":\[\],"complete":true}. Dev.Guide.GetStarted \(A 06gkzpwfthtgf9py7m3qd5dx50, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied\); Dev.Guide.Writing \(A 06gkzpwmgnzph1fb6jp7gf87c0, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied\); Dev.Guide.Addresses \(A 06gkzpwjzhtwb4m72ae1jy3t2c, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied\) GetStarted.FindVault, .Create, .ReadBack; Writing.Create \(fact names come back without a:; t:UntypedEntity\), .ETag \(W/ added on the way, by the edge\), .Put, .Patch; Addresses.Host \(403 "vault target denied" through id.gilb.com, verified 2026-10-15\), .Record, .Ids; Errors.Answer23 \(404 not there, not yours, or another host\). The code example is written here from the routes at 498d29a0, placeholders only. Rows: Developer.WriteThenReadBack, WriteOnVaultHost, GilbPlatform.RecordWrite, RecordRead.

## For developers

### TypeScript: write-and-read-back.ts

```typescript
// Create a record, read it back and change it. headersFor makes Authorization: DPoP <token>
// and a new DPoP proof for one method and address, for example with dpopHeaders from gilb-signin/core.
type Headers = Record<string, string>;

export async function writeAndReadBack(
  vaultId: string, // as GET https://id.gilb.com/lws/vaults gives it
  headersFor: (method: string, url: string) => Promise<Headers>,
): Promise<string> {
  const host = new URL(vaultId).origin; // the vault's own host
  const createUrl = `${host}/lws/vault/${encodeURIComponent(vaultId)}/c`;
  const created = await fetch(createUrl, {
    method: "POST",
    headers: { ...(await headersFor("POST", createUrl)), "content-type": "application/json" },
    body: JSON.stringify({ type: "t:Note", facts: { "a:title": "<a title>" } }),
  });
  if (created.status !== 201) throw new Error(`create answered ${created.status}`);
  const recordUrl = created.headers.get("location")!; // https://<name>.gilb.com/lws/r/<record id>

  const read = await fetch(recordUrl, { headers: await headersFor("GET", recordUrl) });
  if (read.status !== 200) throw new Error(`read answered ${read.status}`);
  const etag = read.headers.get("etag")!;

  const changed = await fetch(recordUrl, {
    method: "PATCH",
    headers: {
      ...(await headersFor("PATCH", recordUrl)),
      "content-type": "application/merge-patch+json",
      "if-match": etag,
    },
    body: JSON.stringify({ "a:title": "<a new title>" }),
  });
  if (changed.status === 412) throw new Error("changed by someone else: read it again");
  if (changed.status !== 200) throw new Error(`change answered ${changed.status}`);
  return changed.headers.get("etag")!; // keep it for the next change
}
```
