Curiosity

Synonyms

A synonym tells search that two terms mean the same thing in your workspace, so a query for one also matches documents containing the other. They exist for the vocabulary the workspace can't guess: internal product codes, team abbreviations, brand names, the shorthand your users type instead of the term your data uses.

Synonyms are applied when a query runs, not when a node is indexed. Adding or changing one takes effect on the next search — there is nothing to rebuild and no re-index to wait for.

What already works without configuration

Before adding anything, check whether the case is already covered. For every query, search also matches:

  • Spelling variants — British/American English (colour ↔ color) and accent-stripped forms (a query for Müller also matches Muller).
  • General-language synonyms — from WordNet (English) and ConceptNet (other languages), for common nouns.
  • Abbreviations and similar terms found in your own data — abbreviations the workspace has learned, and terms that appear in similar contexts across your nodes. The closest of these are already applied to queries; the rest surface as suggestions in the Possible column below.

Configure synonyms for what those miss: domain vocabulary that only means something inside your organization.

Configuring synonyms

Open Settings → Search → Synonyms, on the Predefined Synonyms tab. The list shows every term that has synonyms configured, and what each is linked to.

1

Pick a language

The dropdown above the list scopes what you're editing. Any — the default — applies to queries in every language, which is what you want for product names, SKUs and internal jargon. Pick a specific language for a term that only makes sense there.

2

Type the term in the search box

Existing entries filter as you type. If the term has no entry yet, the box doubles as the input for a new one.

3

Click Add Synonym

Or the pencil icon on an existing row. The editor opens for that term.

4

Fill in the columns and save

The change applies to searches immediately.

The four columns

The editor shows one term — say mbp — and sorts everything related to it into four lists:

Column What it means
Synonyms Treated as equivalent. A search for mbp matches documents containing MacBook Pro at full weight.
Alternates Related, but weaker. They widen what's found without letting the alternate outrank a real match — the right place for a broader or adjacent term.
Possible Suggestions, not active. Terms the workspace derived from your data and from its language resources. Move one into Synonyms, Alternates or Blocked.
Blocked Never used for this term. Blocking suppresses a suggestion that keeps coming back and pulling in irrelevant results.

Each row can be moved between columns, and each Synonyms row has a link toggle.

Synonyms are one-directional unless you link them

Adding MacBook Pro as a synonym of mbp makes a search for mbp find documents saying MacBook Pro. It does not make a search for MacBook Pro find documents saying mbp. Turn on the link toggle on that row to write the reverse direction as well. For abbreviations and product nicknames you almost always want the link on.

Choosing between Synonyms and Alternates

  • Use Synonyms when the two terms are genuinely interchangeable in your data (mbp / MacBook Pro, SSD / solid-state drive).
  • Use Alternates when one term is broader, adjacent, or only sometimes right (laptop as an alternate of mbp). Results still come back, but a document that actually contains the queried term ranks above them.

A term that produces noisy results as a full synonym is usually right as an alternate — try that before removing it.

Synonyms, aliases, or replacements?

Three different features overlap here. Pick by what the alternative name belongs to:

You want Use Where
Two words to mean the same thing everywhere Synonyms Settings → Search → Synonyms
One specific node to be findable under another name Aliases The node's Aliases tab in the node editor
A query's text rewritten before it is parsed (a literal or regex substitution) Replacements Settings → Search → Synonyms → Replacements

Aliases attach to a single node and are folded into the search index, so they need the node to be re-indexed. Synonyms are workspace-wide vocabulary and take effect at once.

From code

The synonyms list is reachable over HTTP for anyone whose account has the Can Manage Synonyms role. Use it to seed vocabulary from an existing glossary or to promote synonyms between environments.

Write the synonyms for one term:

curl -X PUT "https://<your-workspace-host>/api/search/synonyms/for?token=mbp&lang=--&ignoreCase=true&replace=false" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Synonyms":["MacBook Pro"],"Alternates":["laptop"],"Blocked":[]}'
  • token is the term being configured; lang is the language code, -- for Any.
  • replace=false merges with what is already configured; replace=true replaces it.
  • All three lists must be present — send [] for the ones you aren't using.
  • This writes one direction only. To link a pair, send the mirrored request with token=MacBook Pro and "Synonyms":["mbp"].

Read back what a term currently has, including the suggestions:

curl "https://<your-workspace-host>/api/search/synonyms/for?token=mbp&lang=--&tolerance=0.9" \
  -H "Authorization: Bearer $TOKEN"

The response carries Synonyms, Alternates, Blocked, Linked (which of the synonyms point back at the term) and Possible (the scored suggestions). tolerance moves the cut-off for how similar a suggestion has to be, between 0.7 and 1.0.

To list every configured term, GET /api/search/synonyms/list/for?lang=--&includeSynonyms=1. It pages with the X-MSK-SKIP and X-MSK-LIMIT headers and answers { "Results": [[term, linkedTo], …], "TotalCount": n }.

Bulk-loading a glossary

Each write applies immediately and independently, so importing a glossary is a loop over these calls. Every write rebuilds the term matcher for that language, so load a glossary in one pass rather than trickling writes through the day.

You can also ask the admin assistant: "Add the synonyms 'laptop' and 'notebook' to search" — it proposes the change for approval rather than applying it directly. See Change skills.

Things to know

  • Synonyms are not part of configuration sync. They are included when a workspace configuration is exported for inspection, but importing that configuration into another workspace does not restore them — the import reports a warning instead. Move them with the API calls above.
  • A term entered under a specific language is not used for queries in another. Entries under Any apply everywhere; that is the safe default for non-linguistic vocabulary.
  • Blocking is per term, not global — blocking notebook under mbp doesn't block it anywhere else.
  • Nothing needs re-indexing. If a synonym doesn't seem to apply, check the language scope and the direction before suspecting the index.
© 2026 Curiosity. All rights reserved.