cpbox-suggest（cpbox suggest 搜索）

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)

1. First request -> 402 Payment Required with requirements JSON
2. 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