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 team's skills |
| Knowledge | Observations, references, and preferences (private entries require auth) |
| Pages | Published documentation and blog posts |
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 |
|---|---|
| Workspace | 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.
Suggest vs Search
| Endpoint | Auth | Best for |
|---|---|---|
GET /suggest | Optional | Autocomplete, quick discovery, CLI-friendly command hints in results |
GET /search | Required for private knowledge | Scored hits with collection filters and full metadata |
Without a token, /suggest returns public apps and skills. With a token, knowledge in your namespace is included.
/suggest returns a single globally ranked list (not per-collection buckets). Results below the score floor (default 0.8) are dropped. When the same skill or app name exists under multiple namespaces, only the highest-scoring match is kept. Use /search when you need all scored matches in a collection.
CLI: belt suggest (optional --agent, --json, --limit). Scoped: belt app suggest, belt skill suggest. With --json, hook output lists each match as [type] name (ranked by score, deduped server-side) plus a run: command line — see CLI setup. REST and CLI use API version 2 by default — see REST API overview.
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. 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.
- Wait for embeddings — If semantic results seem weak right after create, retry after a moment.
- Use collections — Restrict
/searchtoapps,skills,knowledge, orpageswhen you know what you need. OnGET /search, pass a singlecollectionquery param; onPOST, use thecollectionsarray.
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