How do I list, browse and search the vocabulary?
Short answer
Search with GET /base/terms?q=, walk down with /base/t/<Name>/children, page with /base/vocab, and check a meaning with POST /base/term-requests.
Before you start
Steps 1 to 3 need no account. Step 4 needs a person's sign-in token and the key it is bound to.
Words used here (4)
- sign-in token
- A sign-in token is the credential GilbPlatform issues when a person signs in; your app presents it, with a proof, on each request.
- Actual
- An Actual is how far a delivered step or Solution was measured to move a Value, or how much of a Development Resource it used.
- field
- A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
- GilbPlatform
- GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
Steps
Search the vocabulary by name.
Send the words you look for as q, with no token:
GET https://veda.gilb.com/base/terms?q=<words>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. GilbVeda, the shared list of terms, is searched by each term's name, its other names and its names in other languages, never by its meaning. Every word must match; the last one also matches as the start of a word. Best matches come first, a match on a term's own name above the same match on one of its other names, and at equal rank Approved before Suggested, then Deprecated. The answer holds terms, each with, among others, term, its address, label, does, status and rank; complete; and pageSize, 20 unless you send limit, at most 100. With complete false, send offset, the number of terms you already have. No match answers 200 with no terms and complete true; there is no total.
Walk down the type tree from a term.
Ask for the terms that are a kind of a type, its direct children, with no token:
GET https://veda.gilb.com/base/t/<Name>/childrenMore about this
A Function is what a system does, written as an action; a Value is a perceived benefit, measured as a number. The answer holds type, children and complete; each child has term, name, label, status and kind, type, function or value, in order of label. Start at Thing, the root every type sits under: its children include The Actual, The Imagined & Planned and The Unchanging. One answer holds at most 250 children; complete false says there are more. Functions have no single root: GET https://veda.gilb.com/base/kind/function/parentless lists the functions with no parent, and value in place of function the values with no parent. A name GilbVeda does not have answers 404. To go up, read the term and follow a:subTypeOf, the term it is a kind of; the answer on reading a term by name shows how.
Page through the whole vocabulary.
Ask for the first page, then send each page's next as your next request until complete is true:
GET https://veda.gilb.com/base/vocab?limit=<1 to 2000>More about this
Each page is one JSON-LD document, JSON with a fixed set of names, with the terms in @graph, 500 a page unless you send limit; more than 2000 answers 400 LimitOutOfRange, not a smaller page. next is the whole address of the next page; send the cursor in it as it is: a changed one answers 400 CursorMalformed. This list holds only Approved terms of the published vocabulary. Add status=all for every term with its status, Suggested and Deprecated too, and always send limit with it: without limit, status=all answers the whole list at once. Add nodeKind=<kind>, such as function, to keep one kind. limit, cursor or nodeKind sent twice answers 400 SelectorRepeated.
Check whether a term already carries a meaning.
Send the meaning as JSON in the field meaning, with the person's token and a new DPoP proof:
POST https://veda.gilb.com/base/term-requestsMore about this
The token is the one GilbPlatform gave your app when the person signed in. A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). The body takes only meaning, up to 2000 characters, and the optional app (Deeper); any other key answers 400. The answer's lookup is HIT, one term in use holds that name or key, and term is its address; MISS, none does, and candidates are search hits, never an answer; or REFUSED, a retired term or a refused name, with successors. Several terms holding the name answer 409 with lookup COLLISION. With no token, or a plain Bearer token sent with no proof, the answer is 401 This surface requires an authenticated caller (no token presented). 503 means the lookup could not answer this time.
Deeper
Also asked:
How do I search and browse the vocabulary by API? Search with GET https://veda.gilb.com/base/terms?q=<words>, walk down the type tree with /base/t/<Name>/children, and page through it all with /base/vocab; none of them needs a token.
Steps 1 to 3 need no account, token or proof, change nothing, and a web page on any site may call them. A search answer may be kept for 60 seconds, the others for an hour.
The search asks for q: without it, the answer is 400 querystring must have required property 'q'. An option it does not know, such as cursor, answers 400 querystring must NOT have additional properties. A limit above 100 answers 400 LimitOutOfRange and an offset above 10,000 answers 400 OffsetOutOfRange; the answer is never quietly cut. A Deprecated hit is not for new data: read its address to find the term that replaces it.
The search, the tree and the list hold GilbVeda's terms only. Species are kept apart, in GilbLife, GilbPlatform's list of species.
Step 4 matches a name or a key, with case, hyphens and spaces set aside; words that describe a meaning answer MISS with candidates. Only term on a HIT is an address to store. It writes nothing, unless you add app, the short name of your app: then a HIT sent through Agent.Concept, the agent that finds and makes GilbVeda's terms, records that your app uses the term, and the answer says so under usage; the answer on recording which terms your app uses says more. On a MISS, Agent.Concept makes the term; the answer on minting a term shows how.
Reading one term is in the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.Vocabulary, https://appbuilder.gilb.com/base/e/06gkzpwtj1wm58yf6zng0xdtbm; the search, the tree, the paged list and the meaning check are not in it 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/vocab.ts:1-13 (route list), :55-75 (public by design), :1232-1262 (/base/terms anonymous; empty match = 200, terms [], complete true; unregistered Host 404), :1263-1369 (/base/terms handler: LimitOutOfRange :1272, OffsetOutOfRange :1280, corpus = the veda vault, cache-control public, max-age=60 :1359), :401-416 (termSearchQuerySchema: q required, limit/offset numeric strings, additionalProperties false, no cursor), :640-714 (GET /base/t/:Type/children: anonymous, 404 when the parent is unknown, children term/name/label/status/kind, kindOf type|function|value, sorted by label, complete), :716-769 (GET /base/kind/:nodeKind/parentless), :852-929 (?status=all opt-in listing; without selector and limit the whole listing, :1086-1096; selectors refused, never ignored), :940-996, :1099-1160 (canonical door: one page, VOCAB_PAGE_DEFAULT, next, complete), :512-556 (VocabSelectorError, SelectorRepeated, LimitMalformed, LimitOutOfRange), :562-572 (CursorMalformed); src/vocab/term-reader.ts:38 (DIRECT_CHILD_CAP 250), :472-535 (findDirectChildTerms :488: children = reverse a:subTypeOf, internal excluded, LIMIT cap+1), :545-581 (findParentlessKindTerms :555: live terms of the stored kind with no live a:subTypeOf), :1603 (VOCAB_PAGE_DEFAULT 500), :1610 (VOCAB_PAGE_MAX 2000), :1615-1630 (isMember: published = Approved and planguage-core); src/read/term-search.ts:254 (TERM_PAGE_SIZE 20), :261 (TERM_PAGE_MAX 100), :264 (TERM_OFFSET_MAX 10000), :308 (names matched: a:label, a:synonym, a:searchText; a:does excluded; alt and other-language labels in a:searchText), :361 (SYNONYM_WEIGHT 0.5), :363-420 (PRESENTATION_RANK :416, Approved > Suggested > Deprecated, a tiebreak after relevance), :509-563 (TermHit fields; Deprecated hit: dereference for the successor), :567-600 (complete, pageSize, no count); src/read/bm25-clause.ts:56-80 (bm25Clause :70: every token must match, the last as a prefix); src/routes/term-request.ts:1-20, :43-99 (POST /base/term-requests: requireVerifiedCaller in onRequest before the body; host gate; corpus; lookup; app usage only through Agent.Concept's mark); src/auth/principal.ts:145-158 (only an Authorization: DPoP credential is read; a plain Bearer is null), :550-567 (401 This surface requires an authenticated caller (no token presented)); src/termrequest/answers.ts:38-46 (body closed: meaning 1-2000, optional app), :67-76 (503 CorpusNotServed / CorpusNotLocal), :86-126 (HIT 200 {lookup, term, status, label}; REFUSED 200; COLLISION 409 TermLookupCollision; FAULT 503 LookupUnavailable; MISS 200 candidates, mintRoute); src/termrequest/lookup.ts:1-49 (refusal plane first; held names any status; fold; rank never an answer; writes nothing); docs/BASE-DEVELOPER-GUIDE.md:6672-6700 (team notes at the same revision, read for the fold case ignored; a run of whitespace, hyphens ... is one space, not linked). the code at 498d29a0 shows: no match in src/routes/vocab.ts or src/routes/term-request.ts. Public reads, no token, 2026-11-11: /base/vocab?limit=3 200 limit 3, complete false, next with cursor; ?limit=3000 400 LimitOutOfRange limit must be between 1 and 2000; /base/kind/function/parentless 200; /base/kind/value/parentless 200; /base/t/NoSuchTypeZz/children 404; /base/terms?q=note&limit=2 200, cache-control public, max-age=60, {terms, complete false, pageSize 2}; limit=500 400 LimitOutOfRange; &cursor=x 400 querystring must NOT have additional properties; no q 400 querystring must have required property 'q'; /base/t/Thing/children 200 (Maya The Actual, Kalpana The Imagined & Planned, Brahman The Unchanging, UntypedEntity, complete true); ?nodeKind=function&limit=2 200, next; ?status=all&limit=2 200 with Deprecated terms; ?cursor=abc 400 CursorMalformed. Dev.Guide.Vocabulary (A 06gkzpwtj1wm58yf6zng0xdtbm, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Names, Find, Encodings, Lists.
For developers
curl
search-and-browse.sh
# Search by name. No token is needed. Add &offset=20 for the next 20.
curl -s "https://veda.gilb.com/base/terms?q=<words>"
# One level down the type tree, from the root.
curl -s "https://veda.gilb.com/base/t/Thing/children"
# The functions with no parent.
curl -s "https://veda.gilb.com/base/kind/function/parentless"
# The first page of the whole vocabulary; then call the address in the answer's next.
curl -s "https://veda.gilb.com/base/vocab?limit=500"
TypeScript
walk-vocabulary.ts
type VocabPage = { complete: boolean; next: string | null; "@graph": Record<string, unknown>[] };
// Walks the published vocabulary page by page. No token is needed.
// Never builds a cursor: it only follows the next address the platform gave.
export async function* vocabularyTerms(limit = 500): AsyncGenerator<Record<string, unknown>> {
let url: string | null = `https://veda.gilb.com/base/vocab?limit=${limit}`;
while (url !== null) {
const res: Response = await fetch(url);
if (!res.ok) throw new Error(`vocabulary page answered ${res.status}`);
const page = (await res.json()) as VocabPage;
yield* page["@graph"];
url = page.complete ? null : page.next;
}
}
curl
check-meaning.sh
# Does a term already carry this meaning? Needs the person's token and a new DPoP proof.
curl -s https://veda.gilb.com/base/term-requests \
-H "Authorization: DPoP <sign-in token>" \
-H "DPoP: <a new proof for POST https://veda.gilb.com/base/term-requests>" \
-H "Content-Type: application/json" \
--data '{"meaning":"<a name or a key>"}'
# 200: {"lookup":"HIT","term":"https://veda.gilb.com/base/t/<Name>","status":"Approved","label":"<Name>"}
Checked against GilbApp d529620.