Semantic search (API)

Semantic search ranks your workspace’s assets by meaning instead of keyword overlap: a search for “customer churn” surfaces a dashboard called Retention overview even though neither word appears in its name.

API only — there is no UI for this

Semantic search is two REST endpoints and nothing else. It has no screen anywhere in the product, and it is not exposed as an MCP tool. If you want your users to have it today, you call it yourself.

What it searches

Four kinds of asset, all scoped to the caller’s workspace:

kind	Covers
dashboard	dashboards
metric	governed metrics
model_field	fields across your data models
saved_query	the saved query library

Searching

POST /api/search/semantic, authenticated like any other REST call. No extra scope and no product license are involved — any authenticated caller with a workspace can search it.

curl -X POST https://<your-datasquares-host>/api/search/semantic \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"q": "revenue by region", "kinds": ["dashboard", "metric"], "limit": 5}'

Field	Type	Notes
q	string	required — the natural-language query, up to 1,000 characters
kinds	string[]	optional — any of the four kinds above; omit to search all four
limit	integer	optional — default 20, maximum 100

Hits come back ranked by similarity (score — higher is closer):

{
  "semantic": true,
  "reason": null,
  "hits": [
    {
      "kind": "dashboard",
      "id": "8f3c…",
      "name": "Regional revenue",
      "description": "Bookings and ARR by sales region",
      "score": 0.82,
      "updatedAt": "2026-07-01T09:12:44.000Z",
      "modelId": null,
      "tableId": null
    }
  ]
}

modelId and tableId are filled in for model_field hits only, so you can jump straight to the field’s table.

When it can’t answer

Semantic search degrades honestly rather than failing. When it can’t do the semantic thing, you still get a 200 — with semantic: false, a machine-readable reason, and no hits — so your caller can fall back to plain lexical search:

reason	Means
no_provider	no embedding provider is configured on this instance
embed_failed	the query couldn’t be embedded — the provider errored
index_empty	the query embedded fine, but this workspace has nothing indexed yet

It never raises an error for these cases, and it never dresses keyword matches up as semantic ones. Check semantic before you trust the ranking.

Everyone in the workspace can find everything in it

Results are workspace-scoped, and every hit is re-verified against live permissions before it’s returned, so deleted or invisible entities are dropped. But there is no per-asset ACL: any member of a workspace can find any dashboard, metric, model field or saved query in that workspace. Treat asset names and descriptions as visible to the whole workspace — this endpoint will surface them.

Reindexing

The index maintains itself in the background as assets change, so you normally don’t touch it. An admin can force a rebuild of their workspace’s index:

curl -X POST https://<your-datasquares-host>/api/search/semantic/reindex \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

It reports what it did — scanned, embedded, purged — plus a reason when it couldn’t embed (the same no_provider / embed_failed values as above). Non-admins get a 403.

Related

• MCP server — the other programmatic AI surface, and the one that does have tools.
• AI chat — in-product and conversational.
• Search API reference — the generated endpoint reference.