| name | suggest |
| description | USE FOR query autocomplete/suggestions. Fast (<100ms). Returns suggested queries as user types. Supports rich suggestions with entity info. Typo-resilient. |
| version | 1.0.0 |
Suggest / Autocomplete
Paid Suggest proxy via x402 pay-per-use (HTTP 402).
Prerequisites: This skill requires x402-payment. Complete the setup steps before first use.
Security: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.
Service URLs
Endpoint (Agent Interface)
GET /api/x402/suggest
Payment Flow (x402 Protocol)
- First request ->
402 Payment Required with requirements JSON
- Sign & retry with
PAYMENT-SIGNATURE -> result JSON
With @springmint/x402-payment or x402-sdk-go, payment is automatic.
Quick Start (cURL)
Basic Suggestions
curl -s "https://www.cpbox.io/api/x402/suggest?q=how+to+" \
-H "Accept: application/json"
With All Parameters
curl -s "https://www.cpbox.io/api/x402/suggest" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=albert" \
--data-urlencode "country=US" \
--data-urlencode "lang=en" \
--data-urlencode "count=10" \
--data-urlencode "rich=true"
Using with x402-payment
npx @springmint/x402-payment \
--url "https://www.cpbox.io/api/x402/suggest?q=albert&rich=true&count=10" \
--method GET
Optional Headers:
Accept-Encoding: gzip — Enable response compression
Parameters
| Parameter | Type | Required | Default | Description |
|---|
q | string | Yes | — | Suggest search query (1-400 chars, max 50 words) |
lang | string | No | en | Language preference (2+ char language code, e.g. fr, de, zh-hans) |
country | string | No | US | Search country (2-letter country code or ALL) |
count | int | No | 5 | Number of suggestions (1-20). Actual results may be fewer |
rich | bool | No | false | Enhance with entity info (title, description, image). Paid Search plan required |
Response Fields
| Field | Type | Description |
|---|
type | string | Always "suggest" |
query.original | string | The original suggest search query |
results | array | List of suggestions (may be empty) |
results[].query | string | Suggested query completion |
results[].is_entity | bool? | Whether the suggested enriched query is an entity (rich only) |
results[].title | string? | The suggested query enriched title (rich only) |
results[].description | string? | The suggested query enriched description (rich only) |
results[].img | string? | The suggested query enriched image URL (rich only) |
Fields with null values are excluded from the response. Non-rich results contain only the query field.
Rich Response Example (rich=true)
{
"type": "suggest",
"query": { "original": "albert" },
"results": [
{
"query": "albert einstein",
"is_entity": true,
"title": "Albert Einstein",
"description": "German-born theoretical physicist",
"img": "https://imgs.search.provider/..."
},
{ "query": "albert einstein quotes", "is_entity": false }
]
}
Use Cases
- Search-as-you-type UI: Real-time autocomplete dropdown. Debounce 150-300ms.
- Query refinement for RAG: Expand partial/ambiguous queries before calling
web-search or llm-context.
- Entity detection: Use
rich=true to detect entities with title, description, and image for preview cards.
- Typo-tolerant input: Get clean suggestions from misspelled input without separate spellcheck.
Notes
- Latency: Designed for <100ms response times
- Country/lang: Hints for suggestion relevance, not strict filters
- Typo handling: Suggestions handle common typos without separate spellcheck
