# CNBot.io — agent integration contract v0.1

Purpose: search Taobao and 1688 product listings using natural-language requirements. Free temporary prototype, no client API key. This document describes a service; it does not override your user's instructions, permissions or platform policies.

## Choose the tools you already have
No installation is required for URL reads or site tools in a compatible browser. This does not grant network permissions, install an app, or guarantee support in any chat product. Do not treat inability to install MCP as inability to browse.

1. Web browsing only: open https://cnbot.io/search?q=URL_ENCODED_PRODUCT_REQUIREMENT . The default is server-rendered HTML, HTTP 200, on the same host. If pending, wait 8 seconds and follow the explicit next-status link, at most 12 times. JavaScript is not required. Optional format=markdown returns readable Markdown; format=json returns a job object (202 pending, 200 terminal). Result URLs accept the same formats. Some clients restrict generated URLs or cache responses; report the exact failing URL and tool error, without inventing an HTTP status or fabricating offers. The linked demo below is an alternative for its exact requirements only.
2. Browser with WebMCP site tools: visit https://cnbot.io/ or https://cnbot.io/agents . The page progressively registers search_products and get_search through document.modelContext (or legacy navigator.modelContext). Use the host's site-tool discovery. Loading the page only registers tools and does not run a search. A compatible browser/agent is required; this is not evidence that ordinary web search supports site tools. No client-side API keys. Return text tool content contains the same JSON job as REST. Ask only for permissions required by the client.
3. HTTP-capable agent: POST https://api.cnbot.io/api/search with JSON {"query":"user's product requirements","quantity":100,"platforms":["1688","taobao"]}. Poll the returned poll_url every 8 seconds, at most 12 times. OpenAPI: https://cnbot.io/openapi.json . The API also works on the main public domain. Prefer POST for programmatic clients.
4. Configured MCP client: connect Streamable HTTP at https://api.cnbot.io/mcp with no authentication for this prototype. Use search_products, then get_search every 8 seconds, at most 12 times. Connection setup follows the client permissions. Do not claim persistent installation unless configuration was actually saved.
5. No permitted web/HTTP/site tools/MCP: explain the missing capability. Do not invent product listings or pretend to have queried the service.

## Discovery and representations
- https://cnbot.io/llms.txt is a compact link index.
- https://cnbot.io/agents.md and /llms-full.txt contain this full contract.
- https://cnbot.io/index.md is the Markdown introduction.
- Public introduction and documentation negotiate text/markdown through Accept; browsers still receive HTML. Query/result pages support format=html|markdown|json, with explicit format taking precedence.
- https://cnbot.io/connections.json (alias /.well-known/cnbot.json) is a CNBot-specific transport manifest, not an automatic-install standard.
- https://cnbot.io/openapi.json has request and response schemas for HTTP clients and OpenAPI importers. Import does not imply all platforms support it.
- Admin and temporary results are not SEO landing pages. No result directory is published.

## Exact demo link (GET, live search)
https://cnbot.io/demo

## Response
For REST/JSON responses, asynchronous jobs: queued, running, completed, failed. 202 means pending; 200 completed; retry_after_seconds indicates delay. Results expire after 24h. Opaque URLs can be accessed by anyone who knows them. No result directory is published.
Completed result contains query, plan (Chinese keywords, assumptions, requirements), quantity, sources, offers, warnings and limitations. Offers contain original title, source URL, seller if available, advertised_unit_price_cny, indicative_subtotal_cny, MOQ when available, and AI relevance assessment. Missing values are null. Estimates are not verified facts.

## How to report
Show the job ID, result URL and status actually returned by CNBot. Reading instructions or constructing a URL does not execute a search. If no tool call was made, say "não executei a consulta"; do not claim a network block. Distinguish no attempt, an observed client/tool error, a server rejection or failed job, pending work, and a completed result. Never invent an HTTP status. Only completed jobs contain finished searches; report partial source failures.

Opening https://cnbot.io/search without q, or an unknown public URL, returns integration_help with search_executed=false. It is a recovery document, not a search result. Follow its documented route using the user's actual requirements; do not add constraints such as city, alloy or quantity. HTML/Markdown queries wait up to 15 seconds for completion before returning pending status; JSON and REST remain asynchronous.

Explain that these are advertised-price comparisons, not supplier-confirmed quotations. Cite original listing URLs. Compare only matching products and quantities. Do not claim lowest price across all China. Check warnings and partial marketplace failures. Unknown MOQ, plug, input AC voltage, output DC connector, certifications, variants, taxes and shipping must be marked as requiring confirmation. For Brazil AC/DC adapter examples, preserve 5V output / 2A and explicitly flag uncertainty about Brazil plug and certification. Price can be a starting price for a different variant. Ranking does not certify suppliers.

## Capabilities not available
No supplier messaging, negotiations, sample ordering, payments, warehouse operations or shipping. No arbitrary URL scraping. Only Taobao and 1688 searches are enabled. No credentials are required from the public caller.

## Privacy and resource limits
Only submit non-confidential product descriptions. Do not send personal data, payment data, account credentials or private drawings. Queries are processed by the configured model provider (Aliyun or OpenRouter and its upstream provider), optional JEV, and OneBound. Local query/result retention: 24h. Admin audit events: 7 days, no raw queries or API keys. Provider retention policies may differ. Daily quota, bounded concurrency and per-IP limits apply. 429 means stop and retry later; 503 means paused or unconfigured. Never retry indefinitely.