How do I list records and what changed since?
Short answer
Find the vault id, take a starting cursor with since=head, list the records page by page, then ask for changes with since.
Before you start
Your app holds the token of a person who may read the vault.
Words used here (3)
- record
- A record is one piece of data with its own address, such as a person, a place, a thing or a note.
- vault name
- A vault name is the short name your vault is known by on GilbPlatform: small letters and digits, the first part of its address.
- 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
Find the vault id.
Send this request with the person's token and a new proof, and take vaultId, the vault address to use in other calls, from the vault's entry:
GET https://id.gilb.com/lws/vaultsMore about this
A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). The vault id ends in /vault or /base; use it as given, never built from the vault's name. In the address of a list it is encoded. Encoded means written with encodeURIComponent, so the address fits in one part of the path. A vault name in its place answers 400 vault_name_unresolved; a person's vault named with /base instead of /vault answers 400 WrongVaultRoot and names the right address. The answer on creating a vault, listing vaults and exporting one by API shows the whole list.
Take a starting cursor before you load.
Ask the list for its position now, and keep the nextCursor of the answer:
GET https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?since=headMore about this
The answer has no rows, complete true and a nextCursor. A cursor is a piece of opaque text that marks a place in one list; it works only for the same person, the same vault and the same list, so do not read, edit or build one. Taken before you load, it makes sure a change written while you load comes in step 4. Send the request to the vault's own host, such as https://<name>.gilb.com, with the person's token as in step 1. The list also holds the records of the vaults inside this one that the person may read.
List the records page by page.
Ask for whole records, and set offset to the nextOffset of each answer until complete is true:
GET https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?include=body&offset=<nextOffset>More about this
Start with offset 0. A page holds up to 200 records, newest change first; limit asks for fewer. Each row has entity, the record's address, typeUri, its type, updatedAt, when it last changed, label, its title, and vault and vaultAmbiguous, which say which vault holds it, and with include=body also body, the record as a single read of it gives it, and etag. ETag is a fingerprint of the record's current state. Never count rows to move on: a page stops early at about 8 MiB of records. Without include=body a page holds 20 rows, with no body and no nextOffset. type=<Name>, a bare type name such as Note, keeps one type; it may repeat, for up to 100 names.
Ask for what changed since your cursor.
Send your stored cursor, then store the new nextCursor; while complete is false, ask again at once with it:
GET https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?since=<cursor>&include=bodyMore about this
The answer holds the records created, changed or brought back since the cursor, oldest change first, up to 200 a page. Store nextCursor also when complete is true; it is your next starting place. Put each row under its entity: a record that changed again comes again, and the last one wins. since=start gives every record from the beginning. Keep the same type= on every call of one loop. A change still being written when you ask comes on a later sync. Deleted records are not here: they have their own list and their own cursor, which the answer on listing deleted records shows.
Deeper
Also asked:
How do I fetch only what changed since my last sync? Keep the nextCursor of your last answer and send it as since=<cursor>: the answer holds the records created, changed or brought back since then. Deleted records have their own list.
Can my app be told when a record changes (webhook or live stream)? No: GilbPlatform sends no webhook and has no live stream of changes. Your app asks itself: keep the nextCursor of your last answer and send it as since=<cursor>.
A list that names no vault, such as GET /lws/records, answers 400 vault_target_required. A type= with a bare name that no record carries answers 200 with no rows; a type written as t:Name or as a full address answers 400 type_token_unresolved, not an empty list. More than 100 type names answer 400 type_filter_too_large. include with anything but body answers 400 include must be body, or be left out. A since that is not a cursor this list gave this person for this vault answers 400 since_cursor_invalid; since together with offset answers 400 since_with_offset, and since cannot be combined with after or filter either.
A vault the caller may not read answers 403 vault target denied, before the list's options are checked. The list needs a token, unless the vault is made public as a whole: checked on production on 2026-11-11, with no token, the list of https://appbuilder.gilb.com/base answered 403 vault target denied, although a search there with no token finds its records. The token goes in Authorization: DPoP with a new DPoP proof, 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. The list shows only records the caller may read.
Without type=, the list leaves out files, vaults and the links between records. total is the exact count only on a page with complete true, where totalItemsKind is exact; otherwise it is atLeast, the rows read so far. types counts the types of that page only; the answer on importing and exporting in bulk shows how to count a whole vault by type. To read one type in pages that cost the same however deep, send its nextCursor as after=<nextCursor> with that one type= instead of offset; after cannot be combined with offset, since or lifecycle=ended.
GET /base/nodes also pages record addresses, 200 at a time by offset, but not of one vault: it gives the addresses the caller may read in any vault, not only the vault of the host called, and its total counts all records, readable or not. It takes a DPoP token; a plain Bearer token there counts as no one. For one vault, use the list above.
The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapters Dev.Guide.Reading, https://appbuilder.gilb.com/base/e/06gkzpwp39x2q3dxgj4ytavpvg, and Dev.Guide.Sync, https://appbuilder.gilb.com/base/e/06gkzpwqkxz1h5002g87j1p3x0. 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): src/lws/routes.ts:432-442 (vaultRequired: 400 vault_target_required, use, reachableVaults), :622 and :627 (/lws/records and /lws/types vault-less stubs), :712-727 (GET /lws/vault/:vaultId/records: vaultTarget first, then getRecords), :397-418 (vaultTarget: lwsPrincipal, resolveVaultTarget read); src/authz/vault-target.ts:186-217 (vault_name_unresolved; WrongVaultRoot names https://<host>/vault), :304-330 (403 vault target denied: the principal holds no read reach on vault ...; scope = the named vault plus nested vaults the principal also reaches); src/auth/errors.ts:58-190 (each refusal's error name and message); src/server/app.ts:244-256 (4xx body error, message and details); src/lws/records.ts:118-123 (MAX_TYPES 100, TYPE_NAME bare name), :186-243 (type_token_unresolved, type_filter_too_large), :245-252 (offset), :254-284 (FULL_ROWS_PAGE_CAP 200, FULL_ROWS_BYTE_BUDGET 8 MiB, include must be body, limit clamped, default 200; without include the page is SEARCH_PAGE_SIZE 20, src/read/search.ts:48), :286-293 (lifecycle), :346-366 (gridTypeFrag: no type = no relations, files, vaults, filectl, cost, NON_RECORD_TYPE_LOCALS), :467-531 (refusals before the 200: lifecycle, include, filter, since_with_offset, since_cursor_invalid; since=start, head, cursor), :537-567 (after rules: after_with_offset, after_with_since, after_with_lifecycle, after_requires_one_type, after_cursor_invalid), :594-595 (since=head: no rows, the position now), :687-702 (order: newest change first; since: ascending by time, entity), :940-1003 (row fields; body = the single read's body; byte budget, first row always served; strong etag), :1010-1059 (types = this page only; total, totalItemsKind exact only when complete, nextOffset only with include=body and no since/after, nextCursor stored also when complete); src/lws/since-cursor.ts:1-33 (position, horizon: a transaction still open appears on a later sync; sealed to vault, list and caller), src/lws/resource-frame.ts:1-41 (one builder for the single read and the listed body); src/lws/auth.ts:1-20, :77 (plain Bearer accepted on /lws, DPoP upgrade); src/routes/read.ts:548-660, :845-857 (GET /base/nodes: NODES_PAGE_SIZE 200, offset, total = countEntities, rows = listEntities, both over the whole store, src/read/query.ts:906-941; authenticatedPrincipal, src/auth/principal.ts:51-52, :197-249, a DPoP credential or no one); src/authz/reachable-vaults.ts:248-270 (with no token a vault is listed only through the public fallback, a vault public as a whole). Public reads, no token, 2026-11-11: https://appbuilder.gilb.com/lws/vault/https%3A%2F%2Fappbuilder.gilb.com%2Fbase/records (also with include, since, lifecycle, type=t:Note) 403 vault target denied every time; https://appbuilder.gilb.com/lws/records 400 vault_target_required; https://appbuilder.gilb.com/base/nodes 200, pageSize 200, addresses from three vaults. Dev.Guide.Reading (A 06gkzpwp39x2q3dxgj4ytavpvg), Dev.Guide.Sync (A 06gkzpwqkxz1h5002g87j1p3x0), Dev.Guide.EndAndRevive (A 06gkzpws11z7ba2q7s9qns17h0), Dev.Guide.Addresses (A 06gkzpwjzhtwb4m72ae1jy3t2c), Dev.Guide.Errors (A 06gkzpwxmnxf90zcc3mzc757xg) (pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied); where the Guide and the code differ (Dev.Guide.Errors Limit02: 100 rows with include=body), the page follows the code.
For developers
curl
list-and-sync.sh
# 1. A starting cursor, taken before the first load. Keep nextCursor.
curl -s "https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?since=head" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for this GET>"
# {"total":0,"returnedRecords":0,"complete":true,"records":[],"nextCursor":"<cursor>", ...}
# 2. The first page of whole records. Then send offset=<nextOffset> until complete is true.
curl -s "https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?include=body&offset=0" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for this GET>"
# 3. Later: only what changed since the cursor. Store the new nextCursor every time.
curl -s "https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?since=<cursor>&include=body" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for this GET>"
TypeScript
sync-records.ts
// Load a vault's records once, then keep them in step with since=<cursor>.
// headersFor returns Authorization and a new DPoP proof for one request.
type Headers = (method: string, url: string) => Promise<Record<string, string>>;
type Row = { entity: string; etag?: string; body?: Record<string, unknown> };
type Page = { complete: boolean; records: Row[]; nextOffset?: number; nextCursor?: string };
async function getPage(url: string, headersFor: Headers): Promise<Page> {
const res = await fetch(url, { headers: await headersFor("GET", url) });
if (!res.ok) throw new Error(`list answered ${res.status}: ${await res.text()}`);
return (await res.json()) as Page;
}
export async function firstLoad(list: string, store: Map<string, Row>, headersFor: Headers): Promise<string> {
const head = await getPage(`${list}?since=head`, headersFor);
if (!head.nextCursor) throw new Error("no cursor: since was not understood");
let offset = 0;
for (;;) {
const page = await getPage(`${list}?include=body&offset=${offset}`, headersFor);
for (const row of page.records) store.set(row.entity, row);
if (page.complete || page.nextOffset === undefined) break;
offset = page.nextOffset;
}
return head.nextCursor; // keep it: the next sync starts here
}
export async function syncChanges(list: string, cursor: string, store: Map<string, Row>, headersFor: Headers): Promise<string> {
for (;;) {
const page = await getPage(`${list}?since=${encodeURIComponent(cursor)}&include=body`, headersFor);
for (const row of page.records) store.set(row.entity, row); // the last one wins
if (!page.nextCursor) throw new Error("no cursor: since was not understood");
cursor = page.nextCursor; // store it, also when complete is true
if (page.complete) return cursor;
}
}
// list = `https://<name>.gilb.com/lws/vault/${encodeURIComponent(vaultId)}/records`
Checked against GilbApp d529620.