# How do I import and export in bulk?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

Write an import mapping, send the file with it to POST /base/import, then export the imported records with GET /base/export.

## Before you start

Your app holds [a person's sign-in token](http://support.gilb.com/help/how-do-i-use-the-sign-in-kit) and the key it is bound to. The file is an xlsx workbook \(a spreadsheet\), JSON-LD \(JSON with a fixed set of names\) or N-Triples \(one statement a line\), smaller than about 750 KB. The import takes only a token with [a DPoP proof](http://support.gilb.com/help/how-do-i-make-a-dpop-proof-for-each-request), a short signed note your app makes for one request, naming its method and address \(RFC 9449\).

## Steps

1. Write an import mapping record.

   Create a record of type t:ImportMapping whose facts say how the file becomes records: a:sourceForm, xlsx or jsonld, and the rules. [The answer on creating a record in a vault](http://support.gilb.com/help/how-do-i-create-a-record-in-a-vault) shows how to create one.

   For a workbook, a:sheetRules is a list of {"sheet", "type", "idColumn"}: the type each row of that sheet becomes, and the column, by its heading, whose cell names the row. a:columnRules is a list of {"sheet", "column", "attribute", "coerce"}: which fact each column fills. coerce is string, number, boolean or id; id makes the cell a link. For JSON-LD or N-Triples, a:predicateRules is a list of {"predicate", "attribute", "coerce"}, and rdf:type gives the type. A sheet, column or predicate with no rule, and a row with no id, is left out. The platform reads the rules at each import, so changing them changes the next one. a:sheetRules, a:columnRules and a:predicateRules are not yet terms in GilbVeda, the shared list of terms.
2. Send the file to POST /base/import.

   Send source, the file in base64, which writes its bytes as plain text, mapping, the mapping record's address, and agent, the address that stands for who imports, kept with every fact:
   POST https://id.gilb.com/base/import

   The answer is 201 with entities, each record with changed true or false, constructsIn, the cells or statements read, and constructsMapped, those that became facts. A row of a workbook becomes the record https://&lt;the platform's host\>/base/e/&lt;its id\>, where its id is the text of its id cell with each character other than a letter, a digit, a dot, an underscore, a tilde or a hyphen made a hyphen, so sending the file again changes the same records; a statement's subject is its record's address. Each record goes to the vault its address names, and every one is checked before the first write: one you may not write leaves the whole file unwritten, with 403. Each record keeps a:importSource, where in the file each fact came from.
3. Count a vault's records by type.

   Ask the vault's own host for its type census, with the vault's address put through encodeURIComponent:
   GET https://&lt;name\>.gilb.com/lws/vault/&lt;encoded vault id\>/types

   The answer lists types, each typeUri with a count of the records of that type you may read, and no records. A count of 1000 or more is given as 1000, and totalItemsKind says "atLeast"; count=exact asks for every count in full. excludedTypes names the types left out of the list, with their counts. It takes a plain Bearer token, sent with no proof, as well as DPoP. With no token, or on a vault you may not read, it answers 403 "vault target denied".
4. Export imported records with GET /base/export.

   Name each record with entity, as many times as you need, and choose form, jsonld or xlsx:
   GET https://id.gilb.com/base/export?entity=&lt;record address\>&amp;form=jsonld

   It rebuilds the file the records came from, from their a:importSource: form=jsonld gives N-Triples text, one statement a line, and form=xlsx gives the sheets' cells as XML text, not a workbook file. A record that was not imported, or that you may not read, gives nothing, and no error says so. With no entity it answers 400 "at least one ?entity= is required". Only a token with a DPoP proof is taken; with a plain Bearer token the answer is empty.

## Deeper

Also asked:

Can I write several records in one request, all or nothing? No: each create, PUT, PATCH or DELETE writes one record, and no request writes several records as one all-or-nothing change. POST /base/import writes a file's records one at a time, so a failure part way keeps those already written.

How do I import a file of records, or export them all? Import with a mapping record and POST /base/import; GET /base/export gives back only imported records. To take every record out, list the vault page by page with include=body, or take a copy of the whole vault with its files.

From the code, not checked on production: the platform takes an import only from someone who may write its own home vault, https://&lt;the platform's host\>/base, the vault every workbook row is written to. Anyone else gets 403 "WriteForbiddenError", "is not authorized to import", before the file is read. A mapping address with no record behind it answers 500.

A request body is at most about 1 MiB, so the file, in base64, must fit in it; a larger one answers 413 "Request body is too large". A JSON-LD file may name only the platform's own @context; the platform fetches no other. A body with a field other than source, mapping and agent, or without one of those three, answers 400.

To take every record of a vault out, not only imported ones, read the listing a page at a time with include=body, which gives each record in full; [the answer on listing records and what changed since](http://support.gilb.com/help/how-do-i-list-records-and-what-changed-since) shows how. To copy a whole vault with its files, see [the answer on creating a vault, listing vaults and exporting one by API](http://support.gilb.com/help/how-do-i-create-a-vault-list-vaults-and-export-one-by-api).

The listing is in the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.Reading, https://appbuilder.gilb.com/base/e/06gkzpwp39x2q3dxgj4ytavpvg, and the copy of a vault in its chapter Dev.Guide.Files, https://appbuilder.gilb.com/base/e/06gkzpww3sseh5eskg4h42ts5g; it has no chapter on import yet. 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/routes/import.ts:19-31 \(body source, mapping, agent required; additionalProperties false\), :43-61 \(POST /base/import; writeRequirer; 201\), :63-92 \(GET /base/export; entity repeatable; 400 "at least one ?entity= is required"; form xlsx else jsonld; authenticatedPrincipal + authorizeReadIds: only readable records; text/plain\); src/import/vocab.ts:15-75 \(a:sourceForm, a:columnRules, a:sheetRules, a:predicateRules with their shapes and coerce values; a:importSource; t:ImportMapping; importedEntityUri = https://&lt;ownerHost\>/base/e/&lt;id tail\>\); src/import/import.ts:101-108 \(ImportResult\), :119-136 \(loadMappingSpec; plain Error "Import mapping not found" -\> 500 by src/server/app.ts:244-270\), :170-268 \(sheet, column, predicate with no rule and a row with no id skipped; rdf:type; coerce id -\> link\), :283-358 \(write gate on https://&lt;ownerHost\>/base before parse, WriteForbiddenError "is not authorized to import"; vaultForNamedCreate for every subject before the first write; a:importSource stamped\), :375-420 \(export from a:importSource: N-Triples, xlsx sheet XML\); src/import/parse.ts:1-40, :89-102, :104-130, :360-385 \(xlsx by ZIP, JSON-LD to N-Quads, N-Triples line-wise; no remote @context\); src/auth/principal.ts:269-280 \(writeRequirer = authenticatedPrincipal: DPoP only\); src/write/errors.ts:30-36 \(WriteForbiddenError 403\); src/routes/ai-chat.ts:77 \(Fastify bodyLimit 1 MiB; no bodyLimit set in src\); src/lws/routes.ts:624-627 \(GET /lws/types 400, vault required\), :729-746 \(GET /lws/vault/:vaultId/types; vaultTarget, the /lws Bearer floor\); src/lws/held-types.ts:1-63 \(row-less per-viewer census; types\[{typeUri,count}\], totalItemsKind exact\|atLeast, excludedTypes\), :93-95 \(bound 1000\), :124-130 \(count=exact\). Public read, no token, 2026-11-11: https://appbuilder.gilb.com/lws/vault/https%3A%2F%2Fappbuilder.gilb.com%2Fbase/types 403 "vault target denied: the principal holds no read reach on vault https://appbuilder.gilb.com/base". GilbVeda public reads 2026-11-11: t:ImportMapping \(Suggested\), a:sourceForm 200 \(inline-literal:enum\), a:importSource 200; a:columnRules, a:sheetRules, a:predicateRules 404. Dev.Guide.Errors \(A 06gkzpwxmnxf90zcc3mzc757xg, 2026-11-11\) Answer42 \(413 "Request body is too large"\); Dev.Guide.Reading \(A 06gkzpwp39x2q3dxgj4ytavpvg, 2026-11-11\) List, Walk; Dev.Guide.Files \(A 06gkzpww3sseh5eskg4h42ts5g\). All Standards; read for agreement, not copied. GilbPlatform 0fc5a548 \(live at https://id.gilb.com/version, read 2026-11-14\): src/import/import.ts:323-353 \(one ingestState per record, each its own write\); src/routes/write.ts:109-145 \(POST /base/ingest: one record\); Dev.Guide.Writing \(A 06gkzpwmgnzph1fb6jp7gf87c0, 2026-11-14\): each create, PUT, PATCH and DELETE names one record.

## For developers

### TypeScript: import-file.ts

```typescript
// Send a file to POST /base/import with the address of an import mapping record.
// headersFor gives the Authorization and DPoP headers for one request; a new proof each time.
import { readFile } from "node:fs/promises";

type ImportResult = {
  entities: { entity: string; changed: boolean }[];
  constructsIn: number;
  constructsMapped: number;
};

export async function importFile(
  path: string,
  mapping: string,
  agent: string,
  headersFor: (method: string, url: string) => Promise<Record<string, string>>,
): Promise<ImportResult> {
  const url = "https://id.gilb.com/base/import";
  const source = (await readFile(path)).toString("base64");
  const res = await fetch(url, {
    method: "POST",
    headers: { ...(await headersFor("POST", url)), "Content-Type": "application/json" },
    body: JSON.stringify({ source, mapping, agent }),
  });
  if (res.status !== 201) throw new Error(`import answered ${res.status}: ${await res.text()}`);
  return (await res.json()) as ImportResult;
}
```

### curl: census-and-export.sh

```curl
# Count the records of each type in a vault. Bearer or DPoP; here DPoP with a new proof.
VAULT="<the vault's address, put through encodeURIComponent>"
curl -s "https://<name>.gilb.com/lws/vault/$VAULT/types" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://<name>.gilb.com/lws/vault/$VAULT/types>"
# 200: {"types":[{"typeUri":"t:Note","count":12}, ...],"totalItemsKind":"exact", ...}

# Export two imported records in their source form, as N-Triples.
curl -s -G "https://id.gilb.com/base/export" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://id.gilb.com/base/export>" \
  --data-urlencode "entity=<record address>" \
  --data-urlencode "entity=<another record address>" \
  --data-urlencode "form=jsonld"
```
