{ "openapi": "3.0.3", "info": { "title": "Cross-Border Engine API", "version": "1.1.0", "description": "REST API for cross-border trade intelligence and GEO growth. Authenticate with HMAC-SHA256 (X-Api-Token / X-Api-Signature) or Bearer token. Key power equals your current subscription plan (Model B). MCP clients can consume the same catalog via mcp_server.py." }, "servers": [ { "url": "https://kuajingyinqing.shop", "description": "Global / 海外站" }, { "url": "https://kuajingyinqing.com.cn", "description": "Chinese mainland / 中国大陆站（ICP 备案中，暂不可公网访问）" } ], "components": { "securitySchemes": { "ApiKeyHmac": { "type": "apiKey", "in": "header", "name": "X-Api-Token" }, "Bearer": { "type": "http", "scheme": "bearer" } } }, "paths": { "/api/shop/caps": { "get": { "summary": "Capability matrix for 107 sales platforms (api / rpa / packet / crawl + channel routing)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/shop/skus": { "get": { "summary": "Listable SKU inventory (content-factory output + sourcing ledger + own product table)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/shop/packet": { "post": { "summary": "Build a platform-importable listing package (JSON + CSV, converted to the target marketplace currency, missing images auto-filled)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/shop/publish": { "post": { "summary": "One-click publishing: route by capability official API -> RPA -> data package; never ends on a fake success", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/shop/crawl": { "post": { "summary": "Read/write crawl config (channel / target / frequency / timeout / item limit / proxy / UA)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/shop/packets": { "get": { "summary": "List generated listing packages", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/shop/packet/dump": { "get": { "summary": "Read listing package contents (CSV / JSON, for download and preview)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/risk/meta": { "get": { "summary": "Risk dictionary: queryable countries/regions, platforms and official sources", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/risk/sources": { "get": { "summary": "Official sources and coverage (source count / region count / category counts); no login required", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/risk/query": { "get": { "summary": "Look up bans / recalls / customs controls by product x region x platform (concurrent live fetch; anything unavailable is stated as-is)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/risk/selftest": { "get": { "summary": "Self-test that really calls each of the 16 official sources (availability / latency / sample count / failure reason)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/trade/categories": { "get": { "summary": "Trade categories and flow list (export / import)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/platform/sourcing": { "get": { "summary": "Platform sourcing capability list", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/sourcing/platforms": { "get": { "summary": "Bound / bindable sourcing platforms", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/intel/export/src/sale": { "get": { "summary": "Export side, sourcing perspective, on-sale intel (directional)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/intel/import/src/sale": { "get": { "summary": "Import side, sourcing perspective, on-sale intel (directional)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/sourcing/intel/meta": { "get": { "summary": "Sourcing intel metadata (premium)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/geo/audit": { "post": { "summary": "8-dimension GEO audit (evidence per item + fix order)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to audit; must be publicly reachable" } }, "required": [ "url" ] } } } } } }, "/api/geo/snapshot": { "post": { "summary": "Visibility snapshot (title / description / heading structure / indexability)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } } }, "/api/geo/crawler": { "post": { "summary": "AI crawler reachability (one real request per each of 9 UAs)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } } }, "/api/geo/schema": { "post": { "summary": "JSON-LD structured data extraction", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } } }, "/api/geo/llms": { "post": { "summary": "llms.txt validation (existence / structure / pointers)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } } }, "/api/geo/fix": { "post": { "summary": "Generate fixes (schema / llms.txt / robots / FAQ)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site": { "type": "string" }, "brand": { "type": "string" }, "kind": { "type": "string", "description": "all | schema | llms | robots | faq" } }, "required": [ "site" ] } } } } } }, "/api/ledger/scoreboard": { "get": { "summary": "Forecast hit-rate board (by category; scored records only)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/ledger/predictions": { "get": { "summary": "List forecast records", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "open | hit | miss | unscored" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ] } }, "/api/v1/cbam": { "post": { "summary": "CBAM carbon cost estimate (with basis; not a compliance filing)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "weight_t": { "type": "number" }, "emission_factor": { "type": "number" }, "free_alloc_pct": { "type": "number" }, "fx_cny": { "type": "number" } }, "required": [ "weight_t", "emission_factor" ] } } } } } }, "/api/v1/margin": { "post": { "summary": "True net margin (after commission / shipping / returns)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cost": { "type": "number" }, "price": { "type": "number" }, "commission_pct": { "type": "number" }, "return_rate_pct": { "type": "number" }, "shipping": { "type": "number" } }, "required": [ "cost", "price" ] } } } } } }, "/api/moat/matrix": { "post": { "summary": "Country x HS6 x channel compliance requirement matrix (versioned; admin only)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string" }, "hs6": { "type": "string" }, "channel": { "type": "string" } }, "required": [ "country", "hs6" ] } } } } } }, "/api/v1/missing": { "post": { "summary": "Missing-document list (against the compliance matrix)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "required": { "type": "array" }, "provided": { "type": "array" } }, "required": [ "required", "provided" ] } } } } } }, "/api/v1/origin": { "post": { "summary": "Reverse-derive the best origin path", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hs6": { "type": "string" }, "dest": { "type": "string" }, "candidates": { "type": "array" } }, "required": [ "hs6", "dest", "candidates" ] } } } } } }, "/api/v1/content": { "post": { "summary": "Content structure compliance check (7 signals)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string" } }, "required": [ "html" ] } } } } } }, "/api/v1/gate": { "post": { "summary": "LLM hallucination gate (numeric cross-check)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "facts": { "type": "array" } }, "required": [ "text", "facts" ] } } } } } }, "/api/v1/relevance": { "post": { "summary": "Relevance gate (off-topic detection)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "subject": { "type": "string" }, "must_terms": { "type": "array" }, "deny_terms": { "type": "array" } }, "required": [ "text", "subject" ] } } } } } }, "/api/v1/localize": { "post": { "summary": "Localization quality gate (terminology / language mixing)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "glossary": { "type": "object" }, "required_lang": { "type": "string" } }, "required": [ "text", "glossary" ] } } } } } }, "/api/v1/forecast": { "post": { "summary": "Rolling backtest on a demand series (MAPE)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "type": "array" }, "window": { "type": "integer" } }, "required": [ "series" ] } } } } } }, "/api/v1/scheduler": { "post": { "summary": "Multi-channel collection health and circuit breaking", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array" } }, "required": [ "channels" ] } } } } } }, "/api/v1/match": { "post": { "summary": "Cross-source entity resolution (merge into one product)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "a": { "type": "object" }, "b": { "type": "object" } }, "required": [ "a", "b" ] } } } } } }, "/api/v1/resolve": { "post": { "summary": "Multi-source field conflict arbitration", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array" } }, "required": [ "records" ] } } } } } }, "/api/v1/intent": { "post": { "summary": "Buyer question intent classification", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ] } } } } } }, "/api/v1/stats": { "get": { "summary": "Asset layer overview (status of 12 append-only tables)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/coverage": { "get": { "summary": "Fact-source coverage (honest accounting)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/agents": { "get": { "summary": "Traffic attribution (by UA class)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/verify": { "get": { "summary": "Deliverable fingerprint verification", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "parameters": [ { "name": "sha256", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/api/moat/fact_put": { "post": { "summary": "Write a fact (versioned; standard tier)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "country": { "type": "string" }, "hs6": { "type": "string" }, "item": { "type": "string" }, "value": { "type": "string" } }, "required": [ "kind", "country", "item", "value" ] } } } } } }, "/api/moat/emit": { "post": { "summary": "Emit an outbound event (idempotent + backoff retry)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string" }, "payload": { "type": "object" }, "idem_key": { "type": "string" } }, "required": [ "topic" ] } } } } } }, "/api/moat/moat_index": { "get": { "summary": "32-item moat matrix (A/B/C grading + peer public facts + live probes)", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } }, "parameters": [ { "name": "refresh", "in": "query", "required": false, "schema": { "type": "boolean" } } ] } }, "/api/market/catalog": { "get": { "summary": "105 platforms that can be fetched live (88 sales + 17 overseas sourcing), grouped, each flagged with whether a live path exists", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/market/live": { "get": { "summary": "Fetch real live prices across platforms for a keyword (concurrent; platforms that fail are explicitly marked with a reason, never estimated). Metered: free 3/day, standard 40/day, flagship unlimited; cache hits are not charged", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/predict": { "post": { "summary": "Prediction-model engine: variable selection (stepwise / regularised / PCA), then modelling (logistic / Cox), then evaluation (AUC and C-index, calibration, decision-curve analysis, NRI/IDI, external validation, competing risks) and missing-value handling. Sixteen methods share one definition set; all of it runs server-side and only the result plus its source chapter comes back.", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/skill/list": { "get": { "summary": "能力中心技能清单：按板块分组返回技能名与一句话说明；只给目录与介绍，不返回正文、不返回脚本", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/skill/get": { "get": { "summary": "单个技能详情：对外说明 + 章节目录 + 开头预览；整本正文不返回，响应体有上限", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/skill/ask": { "post": { "summary": "技能内检索：回命中片段与来源章节，单段限量，用于答疑不用于搬运原文", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/skill/run": { "post": { "summary": "技能动作执行：预测 / 洞察 / 决策等内核服务端真算，只回结果与耗时；发布类动作默认演练不对外发", "security": [ { "ApiKeyHmac": [] } ], "responses": { "200": { "description": "OK" } } } } } }