# Search

> Search helps you and your agents find apps, skills, knowledge, and published docs across the platform.

**URL:** https://inference.sh/docs/concepts/search
**Last updated:** 2026-10-11

---

Search helps you and your agents find apps, skills, knowledge, and published docs across the platform.

---

## What gets searched

| Collection | Contents |
|------------|----------|
| **Apps** | Tools in the Grid and your deployed apps |
| **Skills** | Registry skills and your workspace's skills |
| **Knowledge** | Observations, references, and preferences (private entries require auth) |
| **Agents** | Agents in your workspace and public agents |
| **Flows** | Flow definitions. Returned by `/search`, not by `/suggest`. |
| **MCP servers** | MCP servers configured for your workspace |
| **Pages** | Published public documentation and blog posts. Workspace-only and private pages are not indexed. |

Search combines **keyword matching** with **semantic similarity**. When you create or update an entry, it is keyword-searchable right away. Semantic ranking improves after background embedding finishes (usually seconds to minutes).

If query embedding is slow or unavailable (the API allows about **2 seconds** per query), hybrid search **falls back to keyword-only** for that request. Results still return; they may rank differently until semantic search is available again.

---

## Where you use search

| Surface | What it does |
|---------|----------------|
| **Web app** | Unified search bar for apps, skills, and your knowledge |
| **Grid & registry** | Browse and filter by category; search by name and description |
| **Agents** | Agents use `skill_get` for skills; discovery APIs help your own UIs and tools |

For programmatic discovery (autocomplete, filtered search, integrations), use the REST API.

---

## Access control

Search uses the same visibility rules as the list and get APIs. Results are filtered to what you are allowed to see. Another workspace's private content never appears, even when the search index is briefly out of date.

| Caller or visibility | What appears in results |
|----------------------|-------------------------|
| No API key | Public resources only |
| Authenticated | Your workspace's resources according to each entry's `visibility`, plus all public resources |
| `private` | Only the creator, within the owning workspace |
| `team` | All members of the owning workspace |
| `public` | Everyone |

After a visibility change, an out-of-date index can hide a hit until it catches up. It never exposes the entry to callers who are not allowed to see it.

If a resource was removed from the public marketplace (delisted or suspended), search and suggest hide it from everyone except the owning workspace, even when the underlying resource is still `public`. That check runs in Postgres on each query, not in the search index.

Use an API key to search your workspace's content. Public resources are searchable without authentication. Details: [Search API: Access control](/docs/api/rest/search#access-control).

---

## Suggest vs Search

| Endpoint | Auth | Best for |
|----------|------|----------|
| [`GET /suggest`](/docs/api/rest/search#suggest) | Optional | Autocomplete, quick discovery, CLI-friendly `command` hints in results |
| [`GET /search`](/docs/api/rest/search#search) | Required for workspace content | Scored hits with collection filters and full metadata |

Without a token, `/suggest` returns public resources. With a token, your workspace's content is included according to each entry's visibility.

`/suggest` returns a single globally ranked list (not per-collection buckets). The `limit` parameter is a **per-category cap** (default **3** when searching all collections, **10** when filtering to one `category`). Each collection may contribute up to `limit` hits so one type cannot dominate autocomplete. Results below the score floor (default **0.8**) are dropped. Duplicate forks (same content under different namespaces) are collapsed to the highest-scoring match. Use [`/search`](/docs/api/rest/search#search) when you need all scored matches in a collection.

CLI: `belt suggest` (optional `--agent` for directive framing in hook output, `--json`, `--limit`). Scoped: `belt app suggest`, `belt skill suggest`. Suggest result descriptions are clipped to **200 characters**; see [description length limits](/docs/api/rest/overview#description-length-limits). Human-readable output groups results by category with inline `[tag]` labels. With `--json`, hook output lists each match as `[type] name` (ranked by score, deduped server-side) plus a `run:` command line — see [CLI setup](/docs/extend/cli-setup#managing-apps). In hook mode, when stdin includes `transcript_path`, the CLI sends the user's prompt as `query` and up to 1,000 characters of the assistant's previous reply as `context` (not merged into `query`). The API embeds `query` then `context` for semantic ranking so short prompts stay primary. The CLI also sends **scope signals** from your working directory (git remote, language, module name) on every suggest call so project-local knowledge ranks higher. For programmatic clients, `POST /suggest` accepts optional `context` and `scope` that improve semantic ranking without changing keyword matching. Scope tags are appended after the query (and after `context` when set), so they nudge project-local knowledge without outweighing the request — see [Search API](/docs/api/rest/search#suggest). On **SessionEnd**, `belt plugin session-end` posts aggregate session telemetry to `POST /session/end` when you are logged in — see [Search API — Session end](/docs/api/rest/search#session-end-belt-plugin-telemetry). Knowledge entries can store the same scope tags on each version — see [Knowledge — Project scope](/docs/api/rest/knowledge#project-scope).

---

## Knowledge and skills

**Skills** are a dedicated type of knowledge entry. They appear in the `skills` collection and are managed via the [Skills API](/docs/api/rest/skills).

**Other knowledge types** (observations, references, preferences) use the [Knowledge API](/docs/api/rest/knowledge). Tags on entries are searchable. Versions can also carry **project scope** tags (for example `git:github.com/user/repo`, `lang:go`) so `/suggest` boosts entries that match your current workspace — see [Project scope](/docs/api/rest/knowledge#project-scope). To inspect how entries link to each other, use [Get References](/docs/api/rest/knowledge#get-references).

→ [Skills overview](/docs/skills/overview) · [Creating skills](/docs/skills/creating)

---

## Tips

- **Be specific** — Short, descriptive names and tags improve keyword hits. Resource descriptions are capped at **200** characters (**1024** for skills); longer detail belongs in skill instructions or knowledge content.
- **Wait for embeddings** — If semantic results seem weak right after create, retry after a moment.
- **Use collections** — Restrict `/search` to `apps`, `skills`, `knowledge`, `agents`, `flows`, `mcp_servers`, or `pages` when you know what you need. On `GET /search`, pass a single `collection` query param; on `POST`, use the `collections` array.

---

## Next

→ [Search API](/docs/api/rest/search) — request formats, examples, and response fields  
→ [Browsing the Grid](/docs/apps/browsing-grid) — run apps from search results  
→ [The skill registry](/docs/skills/registry) — browse and add public skills