Agent API & MCP

Audience: LLM agents, tool-calling runtimes, and MCP clients (Cursor, Claude Desktop). For human backends and storefronts, use /v1/* + OpenAPI .

AI integrations: MCP and the hiobuy-agent-api Skill expose live China sourcing tools on 1688, Taobao, and Weidian to LLM agents — keyword search, image search, and bilingual product detail for shopping agent workflows in Cursor and Claude Desktop.

Auth: hio_live_* Live keys only. Sandbox keys (hio_test_*) and Sandbox fixtures do not apply to /ai/v1 or /mcp.

Related: Authentication · Products · Response format · Errors · Rate limits

When to use which surface

Tool data payloads match the standard shapes from Product response models and list endpoints — never upstream raw format.

Prerequisites (Live key)

Before calling /ai/v1 or /mcp:

1. Register and create an app in the HIOBuy Developer Portal ; wait for approval.
2. Authorize channels (1688, Taobao, Weidian, …) — same as Portal authorization.
3. Create a Live API key under API Keys (hio_live_* — shown once at creation).
4. Grant scopes for Phase 1 tools at minimum:
   • product:detail — product.get_detail
   • product:search — product.search, product.upload_image, product.search_by_image

Missing channel auth or scope → 401 / 403. Live calls consume channel quota and are logged like /v1.

Base URL & authentication

Same host as Public API, e.g. https://api.hiobuy.com.

Authorization: Bearer hio_live_<your_key>

Each tool maps to an existing API Key scope — there is no separate tools:* scope.

HTTP endpoints (/ai/v1)

List tools

curl -s https://api.hiobuy.com/ai/v1/tools \
  -H "Authorization: Bearer hio_live_xxx"

Returns only tools allowed by the key’s scopes. Each entry includes id, version, domain, description, and JSON Schema input_schema.

Call a tool

POST /ai/v1/tools/call
Authorization: Bearer hio_live_xxx
Content-Type: application/json
 
{
  "tool_id": "product.get_detail",
  "arguments": {
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }
}

Success envelope (all tools):

Failure: HTTP 4xx/5xx with { "error": { "code", "message", "request_id" } } — no ok field. See Errors for shared codes (INVALID_API_KEY, FORBIDDEN, RATE_LIMITED, …).

Phase 1 tools (products)

product.get_detail

• Channel: taobao | 1688 | weidian
• Required: channel + one of product_id | url | mi_id | tao_password
• Optional: language (default en)
• data: { "product": StandardProduct }

product.search

• Required: channel, keyword
• Optional: page, page_size, language, sort, price_start, price_end
• data: StandardProductList (same as POST /v1/products/search body)

product.upload_image

• Channel: 1688 | taobao
• 1688: image_base64 or image_url
• Taobao: image_base64 required
• data: { "channel", "image_id" } — reuse image_id for paginated image search

product.search_by_image

• Channel: 1688 | taobao (not Weidian)
• Input: image_id | image_url | image_base64
• Recommended flow for pagination: product.upload_image once → multiple product.search_by_image calls with image_id only

Agent workflow (HTTP)

1. GET /ai/v1/tools → cache tool metadata / input_schema
2. Model picks tool_id + arguments from user intent
3. POST /ai/v1/tools/call (Bearer hio_live_…)
4. Summarize data for the user

Typical chains:

• One-shot image search: product.search_by_image with image_url or image_base64
• Paginated image search: product.upload_image → product.search_by_image (image_id + page)
• After user picks an item: product.get_detail

MCP server (/mcp) — China sourcing for AI agents

In Cursor, Claude Desktop, and other MCP clients, agents call tools for China sourcing and proxy shopping on 1688 (wholesale), Taobao (retail), and Weidian — keyword search, image upload, image search, and bilingual product detail. Typical shopping agent chains: compare factory quotes on 1688, find Taobao alternatives, browse Weidian catalogs, then drill into SKU/stock via product.get_detail.

The same tool runtime is exposed as an MCP Server over Streamable HTTP (Cursor, Claude Desktop, other MCP clients).

Auth: same Authorization: Bearer hio_live_* header.

Capabilities:

• Tools — tools/list, tools/call (same tool_id values as /ai/v1)
• Prompts — built-in product search / image search / research workflows
• Resources — hiobuy://agent/* URIs (resources/list, resources/read, templates)
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp opens SSE; POST with Accept: text/event-stream may stream JSON-RPC
• Sampling — server may send sampling/createMessage over SSE; client replies via POST /mcp (202)

Recommended session flow:

1. POST initialize → store response header Mcp-Session-Id
2. GET /mcp with session → open SSE listener
3. POST notifications/initialized
4. POST tools/list / tools/call

On success, tools/call → result.content[0].text is the same JSON envelope as /ai/v1/tools/call.

Cursor configuration (shopping agent MCP)

Add to Settings → MCP or .cursor/mcp.json to give Cursor live 1688 / Taobao / Weidian China sourcing tools:

{
  "mcpServers": {
    "hiobuy": {
      "url": "https://api.hiobuy.com/mcp",
      "headers": {
        "Authorization": "Bearer hio_live_xxx"
      }
    }
  }
}

Replace hio_live_xxx with your Live key. Keep keys server-side — do not commit them to public repos.

Cursor Agent Skill (hiobuy-agent-api) — China shopping agent

The optional hiobuy-agent-api Cursor Agent Skill helps coding agents wire 1688, Taobao, and Weidian China sourcing flows — Live-key scopes, /ai/v1 envelopes, MCP session headers, and search → image search → detail tool chains. For REST storefronts on /v1/*, use OpenAPI instead.

It teaches the model:

• Live-key prerequisites and scopes for 1688 / Taobao / Weidian product tools
• /ai/v1 request/response envelopes and Phase 1 tool arguments
• MCP session headers and Cursor mcp.json wiring for China shopping workflows
• Error codes and sourcing tool chains (search → image search → detail)

Install from the public repo hiobuy-agent-skills  — clone or copy SKILL.md into your Cursor skills path (see Cursor Agent Skills ).

git clone https://github.com/hubinjie/hiobuy-agent-skills.git

The skill complements this page — this site remains the canonical API reference for scopes, quotas, and product field semantics.

Quick reference

BASE=https://api.hiobuy.com
KEY=hio_live_xxx
 
curl -s "$BASE/ai/v1/tools" -H "Authorization: Bearer $KEY"
 
curl -s "$BASE/ai/v1/tools/call" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"product.search","arguments":{"channel":"1688","keyword":"phone case","page":1,"page_size":5}}'