Hybrid keyword and semantic search across apps, skills, knowledge, and published pages.

→ Search concept — collections, suggest vs search, and workspace discovery

Suggest

GET /suggest or POST /suggest

Unified search for UI autocomplete and discovery. Returns actionable results ranked globally by relevance score across apps, skills, knowledge, and published pages.

Authentication is optional. Without a token, results are limited to public skills and apps. With a token, knowledge entries in your namespace are included.

Query Parameters (GET)

Field	Type	Required	Description
`q`	string	Yes	Search query
`limit`	integer	No	Max results

Request Body (POST)

GET only reads q. Use POST for limit, category, and agent.

json

1{2  "query": "flux",3  "limit": 10,4  "category": "app",5  "agent": false6}

Field	Type	Default	Description
`query`	string	—	Search query (required)
`limit`	integer	`3` (all categories) or `10` (single category)	Max total results after global ranking and dedup
`category`	string	empty = all	Filter to `app`, `skill`, or `knowledge`. Invalid values return `400`
`agent`	boolean	`false`	Agent mode: full descriptions (no 200-rune truncation) for programmatic consumers

Response

With X-API-Version: 2 (recommended):

json

1{2  "query": "flux",3  "results": [4    {5      "type": "app",6      "name": "pruna/flux-dev",7      "description": "Advanced text-to-image generation...",8      "command": "belt app run pruna/flux-dev",9      "score": 0.9210    },11    {12      "type": "skill",13      "name": "myteam/code-review",14      "description": "Guidelines for reviewing pull requests",15      "command": "belt skill use myteam/code-review",16      "score": 0.8517    }18  ]19}

Field	Description
`type`	Result category: `app`, `skill`, `knowledge`, or page subtype (`doc`, `blog`, …)
`name`	Display name or `namespace/name` for entities
`description`	Short summary (truncated to 200 runes unless `agent: true`)
`command`	Suggested CLI command or doc URL
`score`	Relevance score (0–1)

Results below the relevance floor (default 0.8) are omitted from /suggest responses. When the same base name appears under multiple namespaces, only the highest-scoring variant is returned. Lower-scoring hits may still appear in GET /search when you need broader recall.

Without X-API-Version: 2, the same payload is wrapped in { "success": true, "data": { ... } }. See REST overview — API version.

Example

bash

1curl "https://api.inference.sh/suggest?q=flux&limit=5" \2  -H "X-API-Version: 2"

bash

1curl -X POST https://api.inference.sh/suggest \2  -H "Content-Type: application/json" \3  -H "X-API-Version: 2" \4  -d '{"query": "flux", "limit": 5, "agent": true}'

Search

GET /search or POST /search

Direct search with collection and filter control. Returns scored hits with entity metadata.

Query Parameters (GET)

Field	Type	Required	Description
`q`	string	Yes	Search query
`collections`	string	No	Comma-separated collections: `apps`, `skills`, `knowledge`, `pages`
`limit`	integer	No	Max results per collection

Request Body (POST)

json

1{2  "query": "payment processing",3  "collections": ["knowledge", "skills"],4  "limit": 205}

Response

With X-API-Version: 2 (recommended):

json

1{2  "query": "payment processing",3  "results": [4    {5      "collection": "knowledge",6      "id": "know_abc123",7      "score": 0.87,8      "fields": {9        "name": "stripe-webhooks",10        "namespace": "myteam",11        "description": "Stripe webhook handling patterns",12        "type": "reference",13        "parent_id": "know_abc123",14        "updated_at": 177073201915      }16    }17  ]18}

Without X-API-Version: 2, the same payload is wrapped in { "success": true, "data": { ... } }. See REST overview — API version.

Field	Description
`collection`	Source collection (`apps`, `skills`, `knowledge`, `pages`)
`id`	Entity ID
`score`	Relevance score (0–1)
`fields`	Collection-specific metadata (name, namespace, description, tags, etc.)

Example

bash

1curl "https://api.inference.sh/search?q=flux&collections=apps,skills&limit=10" \2  -H "X-API-Version: 2"

bash

1curl -X POST https://api.inference.sh/search \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2" \4  -H "Content-Type: application/json" \5  -d '{6    "query": "payment processing",7    "collections": ["knowledge"],8    "limit": 209  }'

Use an API key when searching private knowledge entries. Public apps and skills are searchable without authentication.

Collections

Collection	Contents
`apps`	Apps in the grid
`skills`	Skills from the registry and your team
`knowledge`	Observations, references, preferences (requires auth for private entries)
`pages`	Published documentation and blog posts

Search combines keyword matching with semantic similarity. Newly created entities are keyword-searchable immediately; semantic ranking improves after background embedding completes.

If query embedding fails or times out, the API returns keyword-only results for that request (no semantic re-ranking).

Search concept — when to use suggest vs search and what each collection contains
Skills — list, create, and manage skills
Knowledge — manage knowledge entries that appear in search

Suggest

Query Parameters (GET)

Request Body (POST)

Response

Example

Search

Query Parameters (GET)

Request Body (POST)

Response

Example

Collections

Related APIs