How do I list deleted records?
Short answer
Find the vault id, then list the vault's deleted records with lifecycle=ended on its list of records, newest delete first.
Before you start
Your app holds the token of a person who may read the vault.
Words used here (5)
- 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.
- agent
- An agent is your AI following one written procedure, its standing instructions, for one kind of work.
- GilbPlatform
- GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
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.
List the deleted records.
Ask the vault's list for its ended records, with the person's token:
GET https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?lifecycle=endedMore about this
Deleting ends a record; it does not erase it. GilbPlatform keeps the record's address and its history, and an ended record cannot be changed. Each row has entity, the record's address, updatedAt, here the time it was deleted, label, the record's last title, typeUri, its type, vault, the vault it was in, and endingActorKind: holder when it was deleted with a DELETE request, agent when GilbPlatform's AI chat deleted it, left out when that was not recorded. The newest delete comes first, 20 a page; while complete is false, ask again with offset set to the offset plus the rows you got. The list shows the deleted records you may read, in this vault and the vaults inside it that you may read.
To learn of later deletes, use an ended cursor.
Take a cursor for this list before you list it; later, send it, remove each row's entity from your copy, and store the new nextCursor:
GET https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?since=<ended cursor>&lifecycle=endedMore about this
since=head&lifecycle=ended gives the first cursor: no rows 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. A cursor of the live list sent here, or the reverse, answers 400 since_cursor_invalid. The answer holds the records deleted since the cursor, oldest first; while complete is false, ask again at once, and store nextCursor also when complete is true. Match each row by entity, the same text as the record's @id: a deleted record keeps no other fact, such as a:sourceRecordId. Read the live list first and this list after it; the answer on listing records and what changed since shows the live list.
Deeper
Also asked:
How do I list deleted records, and bring one back? List them with lifecycle=ended, as the steps show. To bring one back, send a full PUT to its address with If-Match: * and all its facts: it answers 201 and is live again at the same address; links the delete closed must be made again.
How do I delete (end) a record by API? Send DELETE to the record's address, with your token and a new proof. The record is ended, not erased: it keeps its id and its history, and can be brought back.
With include=body each row also has body and etag, but body is only an end marker: @context, @id, @type, a:entityLifecycleState ended and a:endingActorKind. It does not hold the old content, and every ended row has the same etag. A single GET of a deleted record you may read answers 200 with the same end marker. A change to a deleted record answers 409 EntityEndedError; a second DELETE answers 404.
A record can be brought back: writing the record again in full, with all its fields, at its own address makes it live again, in the vault it was in. Links the delete closed stay closed and must be made again. It then leaves the deleted list and comes on the live list again, with the same address. The Developer Guide shows how, in its chapter Dev.Guide.EndAndRevive, https://appbuilder.gilb.com/base/e/06gkzpws11z7ba2q7s9qns17h0.
Without type=, the list leaves out files, vaults and the links between records. A list that names no vault answers 400 vault_target_required, a vault the caller may not read answers 403 vault target denied, and lifecycle with anything but live or ended answers 400 lifecycle must be live (default) or ended. after cannot be used here: it answers 400 after_with_lifecycle. 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 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:712-727 (one route for both lists), :432-442 (vault_target_required); src/authz/vault-target.ts:186-217, :304-330 (vault_name_unresolved, WrongVaultRoot, 403 vault target denied, nested vaults in scope); src/lws/records.ts:146-166 (endingActorKind holder/agent/omitted; vault, vaultAmbiguous always false on the ended set; label the last closed label), :286-293 and :467-474 (lifecycle live|ended, else 400 lifecycle must be live (default) or ended), :546-550 (after_with_lifecycle), :687-765 (ended candidates: ended_at not null, ended_in_vault in scope; updatedAt = ended_at; newest end first; since: ascending), :245-252 and :1050-1053 (plain list: offset, no nextOffset), :940-1003 (body built by the single read's builder); src/lws/resource-frame.ts:27-41 (ended document: a:entityLifecycleState ended, a:endingActorKind when recorded); src/lws/crud.ts:36-44 (DELETE closes every current fact and stamps ended_at, ended_in_vault, ending_actor_kind; history kept); src/lws/since-cursor.ts:1-33, :53-66 (cursor sealed to lifecycle, vault and caller); src/auth/errors.ts:96-104 (since_cursor_invalid); src/write/ingest.ts:2354-2363 (a revive clears ended_at, so the record leaves the ended list); src/lws/auth.ts:1-20 (plain Bearer on /lws); src/lws/routes.ts:1101-1105 (DELETE /lws/r/:id stamps holder: Actor kind is WHICH DOOR), src/ai/vault-tools.ts:2676 (the AI chat's delete stamps agent), src/lws/crud.ts:71, :728; src/authz/reachable-vaults.ts:248-270 (no token: only a vault public as a whole). GilbVeda t:EndingActorKind (Suggested; public read https://veda.gilb.com/base/terms?q=endingActorKind, 2026-11-11: "whether an entity's ending was performed by the vault's HOLDER acting for themselves (holder) or by an ASSISTANT acting inside the holder's session (agent)"); t:EntityLifecycleState (Suggested; The only member of the token set is ended). Public read, no token, 2026-11-11: the ended list of https://appbuilder.gilb.com/base answered 403 vault target denied. 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) Dev.Guide.Reading.Ended, Dev.Guide.Sync.Ends (matching by entity, not a:sourceRecordId; verified on production 2026-10-16 and 2026-10-21), Dev.Guide.EndAndRevive.ReadEnded, NoChangeWhileEnded, Revive, Links. Read 14 November 2026: Dev.Guide.EndAndRevive (A 06gkzpws11z7ba2q7s9qns17h0, pack GilbPlatformDeveloperGuide) Revive, OwnVault, Links.
For developers
curl
deleted.sh
# The deleted records of a vault, newest delete first, 20 a page.
curl -s "https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?lifecycle=ended&offset=0" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for this GET>"
# A cursor for the deleted list. Keep it apart from the live list's cursor.
curl -s "https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?since=head&lifecycle=ended" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for this GET>"
# Later: only the records deleted since that cursor. Store the new nextCursor.
curl -s "https://<name>.gilb.com/lws/vault/<vault id, encoded>/records?since=<ended cursor>&lifecycle=ended" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for this GET>"
TypeScript
remove-deleted.ts
// Remove from your copy the records deleted since the ended cursor; return the new cursor.
// headersFor returns Authorization and a new DPoP proof for one request.
type Headers = (method: string, url: string) => Promise<Record<string, string>>;
type EndedRow = { entity: string; updatedAt: string; endingActorKind?: "holder" | "agent" };
type Page = { complete: boolean; records: EndedRow[]; nextCursor?: string };
export async function removeDeleted(
list: string, endedCursor: string, store: Map<string, unknown>, headersFor: Headers,
): Promise<string> {
let cursor = endedCursor;
for (;;) {
const url = `${list}?since=${encodeURIComponent(cursor)}&lifecycle=ended`;
const res = await fetch(url, { headers: await headersFor("GET", url) });
if (!res.ok) throw new Error(`ended list answered ${res.status}: ${await res.text()}`);
const page = (await res.json()) as Page;
for (const row of page.records) store.delete(row.entity); // match by entity, never by another fact
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.