Search

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

---

What gets searched

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

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.

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.

---

Suggest vs Search

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 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. 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. 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. On SessionEnd, belt plugin session-end posts aggregate session telemetry to POST /session/end when you are logged in — see Search API — Session end. Knowledge entries can store the same scope tags on each version — see 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.

Other knowledge types (observations, references, preferences) use the Knowledge API. 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. To inspect how entries link to each other, use Get References.

→ Skills overview · Creating skills

---

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 — request formats, examples, and response fields
→ Browsing the Grid — run apps from search results
→ The skill registry — browse and add public skills