← The vocabulary (GilbVeda terms by API)
How do I record which terms my app uses?
Short answer
Read who uses a term with GET /base/registry/usage, record your app with gilb-mint.ts search --app, then read your terms back in bulk.
Before you start
Steps 1 and 3 need no account. Step 2 needs gilb-mint.ts signed in on your computer, as the answer on minting a term shows.
Words used here (4)
- record
- A record is one piece of data with its own address, such as a person, a place, a thing or a note.
- field
- A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
- agent
- An agent is your AI following one written procedure, its standing instructions, for one kind of work.
- short name
- A short name is the one word you give one AI on one computer, such as gilb-example; it keeps that AI's key and tools apart.
Steps
Read which apps use a term.
Send the term's whole address, encoded, as term, with no token:
GET https://veda.gilb.com/base/registry/usage?term=<the term's address, encoded>More about this
A term is the shared name GilbVeda keeps for a kind of thing, a detail of it, a link between two things, or a species. Encoded means written with encodeURIComponent, so the address fits in one query value. The answer holds usageCount, the number of usage records, one for each app recorded; usedByApp, the names of those apps, 20 a page unless you send limit, at most 100; complete; and pageSize. With complete false, send offset, the number of names you already have. Write the whole address, such as https://veda.gilb.com/base/t/Note: t:Note, a misspelt address and a term GilbVeda does not have all answer 200 with usageCount 0. A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda. A field's term has two addresses, /base/t/<Name> and /base/a/<name>, and each is counted alone, so ask for both.
Record your app's use when you look the term up.
Have your AI act as Agent.Concept, the agent that finds and makes GilbVeda's terms, and search for the term, naming your app with --app, its short name with no spaces:
node ~/.gilb/kit/gilb-mint.ts search <the term's name or meaning> --app <your app>More about this
On a HIT (a live term carries your meaning), the platform records that your app uses the term, under each address the term answers under, and the program prints usage: recorded for and your app's name, with (already on record) when it was there before. Any other answer records nothing, and the program prints usage: NOT recorded for your app and why, such as NotAHit after a MISS (no term carries it). A term you mint for your app is recorded in the same write when its member names app; the answer on minting a term shows how. Your sign-in is kept as who recorded the use. One person may record 200 uses in 24 hours; past that the reason is UsageQuotaReached.
Read your terms back in one request.
Send the terms' whole addresses, each encoded, separated by commas, at most 100, with no token:
GET https://veda.gilb.com/base/registry/usage/bulk?terms=<address>,<address>More about this
The answer holds usage, with one entry for each address exactly as you sent it, and termCount. Each entry has usageCount, usedByApp, at most 32 names in the order of the alphabet, and appsTruncated, true when the term has more apps than the list shows. A use you have just recorded may take a minute to show: these answers may be kept for 60 seconds. Commas with no address answer 400 NoTermsNamed; terms left out or empty answers 400 with a message that it is required or too short; more than 100 answer 400 TooManyTerms.
Deeper
Both reads need no account, token or proof, change nothing, and a web page on any site may call them. Each answer carries an etag, a short code that changes when the answer changes; send it back in the If-None-Match header, and an answer that has not changed comes back as 304, Not Modified, with no body. A limit outside 1 to 100 answers 400 LimitOutOfRange, an offset above 10,000 answers 400 OffsetOutOfRange, and an option the read does not take answers 400 querystring must NOT have additional properties.
A recorded use says an app was named as using the term; it is not proof that it does. Anyone signed in may name any app, and each record keeps who wrote it. An empty answer proves nothing either: usageCount 0 comes back alike for a term no app named, a term that does not exist and an address written another way. Before Agent.Concept changes a term in use, it reads this list; the answer on changing or retiring a term you minted says more.
Uses are recorded only through Agent.Concept. POST /base/registry/usage also records a use, but only for the platform's owner. From your own code, POST https://veda.gilb.com/base/term-requests with meaning and app records a HIT only when the request carries the pass the server gives an Agent.Concept turn, in X-Base-Mint-Pass; the mint program fetches it for you, and the answer on minting a term shows the requests. Without it the lookup still answers, and usage says recorded false and NotThroughAgentConcept. app holds no spaces and at most 256 characters, or the answer is 400. A change to a term records no use. In GilbApp's chat, Agent.Concept records the use when you name your app, and the answer on seeing where a term is used shows the count in GilbApp.
Recording which terms an app uses is not in the Developer Guide, GilbPlatform's guide for people who build apps on it, yet; its chapter Dev.Guide.Vocabulary, https://appbuilder.gilb.com/base/e/06gkzpwtj1wm58yf6zng0xdtbm, shows how to read a term. 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/vocab.ts:1371-1452 (GET /base/registry/usage: anonymous, LimitOutOfRange 1-100, OffsetOutOfRange 0-10,000, crosses to the corpus, {term, usageCount, usedByApp, complete, pageSize}, cache-control public, max-age=60, etag, 304), :423-432 (query schema: term required, limit, offset, additionalProperties false), :1454-1538 (GET /base/registry/usage/bulk: NoTermsNamed, TooManyTerms over 100, keyed by the caller's string, {usage, termCount}, max-age=60, etag), :451-458, :1540-1632 (POST /base/registry/usage: requireOwner, owner only); src/read/term-usage.ts:60-195 (usageCount = count of t/TermUsage rows for the exact term; usedByApp page ordered by row; complete by limit+1), :197-350 (bulk: BULK_APPS_PER_TERM_CAP 32, array_agg DISTINCT ORDER BY app, appsTruncated); src/routes/term-request.ts:1-105 (app optional; a HIT with app records only through mayMintTerms and the pass; else usage {recorded false, reason NotThroughAgentConcept, message}); src/termrequest/hit-usage.ts:1-89 (NotAHit; under each address; writer = the verified caller; UsageQuotaReached; UsageWriteFailed); src/termrequest/usage-quota.ts:13-35 (200 a person per 24 h); src/termrequest/answers.ts:29-46 (body closed: meaning 1-2000, app 1-256, APP_SLUG_RE); src/termrequest/mint.ts:66-98 (app on a member, written in the same transaction), :1223-1244 (usageFormsOf: /t/ and /a/); src/routes/term-mint.ts:256-262 (app on a change 400). scripts/devkit/gilb-mint.ts:41-45 (id.gilb.com, veda.gilb.com, life.gilb.com), :186-239 (usage text), :271-317 (signin: request-code; code: verify-code with the kit's own P-256 key; ~/.gilb/mint-credential.json 0600; expiry check), :324-357 (passFor: POST <base>/base/ai/claude-code/context with agent Agent.Concept, mintPasses.vocab|life; needsPass for POST /base/vocab/, /base/life/mint, /base/term-requests), :502-540 (search: one https IRI = GilbLife taxonID; words = term-requests then GilbLife scientificName; --app prints usage: recorded for / usage: NOT recorded for), :542-581 (mint/change/retire routing; the shipped example refused locally, exit 2); scripts/devkit/README.md:21-36 (Node 22.18+ or 23.6+; 6-digit code 10 minutes; credential 7 days), :38-83 (the loop, answers, exit codes 0/1/2, dropped connection), :85-143 (GilbLife), :171-184 (a member); scripts/devkit/example-package.json (an attribute and its Value). src/routes/_mint-gate.ts:1-42 (one gate for terms and GilbLife: host 404, mayMintTerms 401/403, vault served and local 503, pass 403 NotThroughAgentConcept New ontology is minted through Agent.Concept only. ...), :92-128; src/auth/mint-pass.ts:1-66 (pass issued by the server for an Agent.Concept turn; header x-base-mint-pass; aud base:mint:vocab or base:mint:life; 15 minutes; sub = the person); src/routes/ai-claude-code.ts:271-298 (POST /base/ai/claude-code/context: mintPasses only on an Agent.Concept turn and when mayMintTerms passes), :114-127 (body: userText required, agent, agentEntry, contentVaultIds, turnId); src/auth/open-mint-standing.ts:1-110 (a signed-in person or a bound AI; computer credential or unbound machine 403 NotAPersonToMint; no http principal 401 SignInToMint). docs/BASE-DEVELOPER-GUIDE.md:26 (team note at this revision, read for agreement: Anyone signed in can currently credit any app name; a declared claim, not proof; not linked). Public reads, no token, 2026-11-11: usage?term=<veda>/t/Note 200 usageCount 2, access-control-allow-origin *, cache-control public, max-age=60, etag; <veda>/a/title 200 6 apps; term=t:Note 200 usageCount 0; <veda>/t/NoSuchTermXyz 200 0; no term 400 querystring must have required property 'term'; limit=101 and limit=0 400 LimitOutOfRange; offset=10001 400 OffsetOutOfRange; foo=1 400 querystring must NOT have additional properties; limit=2 complete false, offset=2 the next two; bulk with three keys 200 {usage, termCount 3}, t:Note 0; bulk terms=, 400 NoTermsNamed; https://id.gilb.com/base/registry/usage 200, same answer. Proc_v_i_bv_CrossAppTermReuse (J 06gf2n624dty36phxgcm43q0j0) steps 2-3 (ask both addresses of an attribute; an empty answer licenses nothing). Agent.Concept (J 06gf80rjtdw3h9q187p80kx00m, 2026-11-11): Task (any signed-in person; terminal: node ~/.gilb/kit/gilb-mint.ts, which the one setup link installs; look up by name and by meaning; HIT = use it; MISS = mint at once; usage row; no record stands in), ClosedSend, PictureLicence. Dev.Guide.Vocabulary (A 06gkzpwtj1wm58yf6zng0xdtbm): no usage part. Shared sentences, word for word: term, field, the recorded-use sentence.
For developers
curl
read-usage.sh
# Which apps are recorded as using one term? No token is needed.
# Send the term's whole address, encoded.
curl -s "https://veda.gilb.com/base/registry/usage?term=<the term's address, encoded>"
# {"term":"https://veda.gilb.com/base/t/<Name>","usageCount":2,"usedByApp":["<app>","<app>"],"complete":true,"pageSize":20}
# Up to 100 terms in one request. For a field's term, send both of its addresses.
curl -s "https://veda.gilb.com/base/registry/usage/bulk?terms=<address, encoded>,<address, encoded>"
# {"usage":{"<address>":{"usageCount":2,"usedByApp":["<app>","<app>"],"appsTruncated":false}, ...},"termCount":2}
TypeScript
usage-of-terms.ts
type Usage = { usageCount: number; usedByApp: string[]; appsTruncated: boolean };
// Reads which apps are recorded as using each term. No token is needed.
// Pass whole addresses, such as https://veda.gilb.com/base/t/<Name>; for a field's term
// pass both of its addresses, /base/t/<Name> and /base/a/<name>.
export async function usageOf(addresses: string[]): Promise<Map<string, Usage>> {
const found = new Map<string, Usage>();
for (let i = 0; i < addresses.length; i += 100) {
const terms = addresses.slice(i, i + 100).map(encodeURIComponent).join(",");
const res = await fetch(`https://veda.gilb.com/base/registry/usage/bulk?terms=${terms}`);
if (!res.ok) throw new Error(`usage read answered ${res.status}: ${await res.text()}`);
const body = (await res.json()) as { usage: Record<string, Usage> };
for (const [address, usage] of Object.entries(body.usage)) found.set(address, usage);
}
return found; // usageCount 0 is no proof that no app uses a term
}
Checked against GilbApp d529620.