# How do I list, browse and search the vocabulary?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

Search with GET /base/terms?q=, walk down with /base/t/&lt;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](http://support.gilb.com/help/how-do-i-use-the-sign-in-kit) and the key it is bound to.

## Steps

1. Search the vocabulary by name.

   Send the words you look for as q, with no token:
   GET https://veda.gilb.com/base/terms?q=&lt;words\>

   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.
2. 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/&lt;Name\>/children

   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 &amp; 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](http://support.gilb.com/help/how-do-i-read-a-term-by-name-and-the-json-ld-context) shows how.
3. 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=&lt;1 to 2000\>

   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=&lt;kind\>, such as function, to keep one kind. limit, cursor or nodeKind sent twice answers 400 "SelectorRepeated".
4. 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](http://support.gilb.com/help/how-do-i-make-a-dpop-proof-for-each-request):
   POST https://veda.gilb.com/base/term-requests

   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=&lt;words\>, walk down the type tree with /base/t/&lt;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](http://support.gilb.com/help/how-do-i-record-which-terms-my-app-uses) says more. On a "MISS", Agent.Concept makes the term; [the answer on minting a term](http://support.gilb.com/help/how-do-i-mint-a-term-from-code-the-terminal-kit-or-chat) 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&amp;limit=2 200, cache-control public, max-age=60, {terms, complete false, pageSize 2}; limit=500 400 LimitOutOfRange; &amp;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 &amp; Planned", Brahman "The Unchanging", UntypedEntity, complete true\); ?nodeKind=function&amp;limit=2 200, next; ?status=all&amp;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

```curl
# 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

```typescript
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

```curl
# 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>"}
```
