{
  "openapi": "3.1.0",
  "info": {
    "title": "SiLink Business Functions API",
    "version": "1.0",
    "description": "One generic endpoint — pass a service_code to select the business function. SiLink prices outcomes, not model tokens: a call either delivers the result or is automatically refunded.\n\nRate limits (per API key, 60s sliding window): max: 60/min, business: 600/min.\n\nVolume discounts (per account, calendar month): 0-1000 calls/month: 0% off; 1001-10000 calls/month: 10% off; 10001-100000 calls/month: 20% off. Above the top tier: custom quote.\n\nAsync mode: pass \"async\": true on report.new_product_intelligence or report.target_list_export (the two slowest calls) to get a 202 with a job_id immediately instead of blocking for up to 3 minutes. Poll GET /jobs/{job_id}, or set callback_url for a webhook — either way the result is retrievable even if the webhook delivery ultimately fails.",
    "contact": {
      "url": "https://silink.ai/contact"
    }
  },
  "servers": [
    {
      "url": "https://silink.ai"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Business Functions"
    }
  ],
  "paths": {
    "/api/v1/business/run": {
      "post": {
        "tags": [
          "Business Functions"
        ],
        "operationId": "runBusinessFunction",
        "summary": "Run a business function",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/RunRequest_verify_brand_check"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_verify_deep_risk_check"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_build_naming"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_discover_buyers"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_discover_suppliers"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_report_new_product_intelligence"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_report_target_list_export"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_report_industry_overview"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_decide_province"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_discover_cn_buyers"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_decide_compare_suppliers_5"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_discover_competitors"
                  },
                  {
                    "$ref": "#/components/schemas/RunRequest_decide_market"
                  }
                ],
                "discriminator": {
                  "propertyName": "service_code",
                  "mapping": {
                    "verify.brand_check": "#/components/schemas/RunRequest_verify_brand_check",
                    "verify.deep_risk_check": "#/components/schemas/RunRequest_verify_deep_risk_check",
                    "build.naming": "#/components/schemas/RunRequest_build_naming",
                    "discover.buyers": "#/components/schemas/RunRequest_discover_buyers",
                    "discover.suppliers": "#/components/schemas/RunRequest_discover_suppliers",
                    "report.new_product_intelligence": "#/components/schemas/RunRequest_report_new_product_intelligence",
                    "report.target_list_export": "#/components/schemas/RunRequest_report_target_list_export",
                    "report.industry_overview": "#/components/schemas/RunRequest_report_industry_overview",
                    "decide.province": "#/components/schemas/RunRequest_decide_province",
                    "discover.cn_buyers": "#/components/schemas/RunRequest_discover_cn_buyers",
                    "decide.compare_suppliers_5": "#/components/schemas/RunRequest_decide_compare_suppliers_5",
                    "discover.competitors": "#/components/schemas/RunRequest_discover_competitors",
                    "decide.market": "#/components/schemas/RunRequest_decide_market"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success, or (non-pooled services only) automatic charge failed with ok=false.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/RunResponsePooled"
                    },
                    {
                      "$ref": "#/components/schemas/RunResponseNonPooled"
                    },
                    {
                      "$ref": "#/components/schemas/OffsessionChargeFailed"
                    }
                  ]
                }
              }
            }
          },
          "202": {
            "description": "Accepted for background processing. Only returned when async:true was set on one of the async-capable service_codes; charging already happened, see AsyncJobAccepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsyncJobAccepted"
                }
              }
            }
          },
          "400": {
            "description": "unknown_service_code, engine_rejected_input (charge automatically refunded), async_not_supported (async:true on a service_code that doesn't support it — body lists which ones do), or invalid_callback_url",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_sptok, or volume_over_limit (>100k calls this month, contact us)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "tier_insufficient — Max or Business subscription required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — body includes retry_after (seconds) and limit_per_min",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "500": {
            "description": "engine_error (charge automatically refunded)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "charge_backend_error — payment backend unavailable, nothing was charged, safe to retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/business/jobs/{job_id}": {
      "get": {
        "tags": [
          "Business Functions"
        ],
        "operationId": "getJobStatus",
        "summary": "Poll an async job's status/result",
        "description": "Works whether or not callback_url was set — this is the pull side of async mode. If a callback was requested and its delivery attempts are exhausted, the result is still only retrievable here.",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStatus"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "not_your_job",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "job_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/business/services": {
      "get": {
        "tags": [
          "Business Functions"
        ],
        "operationId": "listBusinessServices",
        "summary": "List service_codes, prices and payload fields available to this key",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServicesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "tier_insufficient",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/business/checkout/{session_id}/deliver": {
      "post": {
        "tags": [
          "Business Functions"
        ],
        "operationId": "deliverCheckoutResult",
        "summary": "After paying via checkout_url, run the service and get the result",
        "description": "Only for non-pooled services whose automatic charge failed. Idempotent: repeat calls replay the stored result and never charge twice. Returns 402 checkout_pending until the Stripe session is paid.",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delivered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutDeliverResponse"
                }
              }
            }
          },
          "400": {
            "description": "checkout_invalid, or engine_rejected_input (spTok refunded)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "checkout_pending — payment not completed yet; body includes checkout_url",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "not_your_checkout",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_checkout_session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "engine_error (spTok refunded)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/business/reports/{kind}/{sig}/download": {
      "get": {
        "tags": [
          "Business Functions"
        ],
        "operationId": "downloadBusinessReport",
        "summary": "Download a report file produced by a report.* service",
        "description": "Use the download_urls returned by the report service. Only the key that paid for the report can download it.",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "industry_overview",
                "target_list"
              ]
            }
          },
          {
            "name": "sig",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fmt",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pdf",
                "docx",
                "md",
                "txt"
              ],
              "default": "pdf"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "bad_fmt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or inactive API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "not_your_report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_report_kind / report_not_found / file_missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from /business-api-console. Max or Business subscription required."
      }
    },
    "schemas": {
      "Payload_verify_brand_check": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string",
            "description": "Brand name (required)",
            "x-description-zh": "品牌名(必填)"
          },
          "markets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of target market IDs, see brand_check.MARKETS",
            "x-description-zh": "目标市场id列表,见brand_check.MARKETS"
          }
        },
        "required": [
          "brand"
        ]
      },
      "RunRequest_verify_brand_check": {
        "type": "object",
        "description": "Brand Check (Outbound/China). USD 99 per call. billed from the monthly spTok pool",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "verify.brand_check"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_verify_brand_check"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 99,
        "x-pooled": true,
        "x-category": "verify",
        "x-name-zh": "出海品牌核查／中国品牌核查"
      },
      "Payload_verify_deep_risk_check": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string",
            "description": "Company's full legal name or 18-digit Unified Social Credit Code (required)",
            "x-description-zh": "企业全称或18位统一社会信用代码(必填)"
          }
        },
        "required": [
          "identifier"
        ]
      },
      "RunRequest_verify_deep_risk_check": {
        "type": "object",
        "description": "Deep Risk Check (litigation/history). USD 49 per call. billed from the monthly spTok pool",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "verify.deep_risk_check"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_verify_deep_risk_check"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 49,
        "x-pooled": true,
        "x-category": "verify",
        "x-name-zh": "企业深度风险核验（诉讼/失信/变更）"
      },
      "Payload_build_naming": {
        "type": "object",
        "properties": {
          "company": {
            "type": "string",
            "description": "Chinese company's full legal name (required)",
            "x-description-zh": "中文企业全称(必填)"
          }
        },
        "required": [
          "company"
        ]
      },
      "RunRequest_build_naming": {
        "type": "object",
        "description": "Company Naming/Rename/English Name. USD 39 per call. billed from the monthly spTok pool",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "build.naming"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_build_naming"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 39,
        "x-pooled": true,
        "x-category": "build",
        "x-name-zh": "企业起名／更名／取英文名"
      },
      "Payload_discover_buyers": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string",
            "description": "Product/requirement description (required)",
            "x-description-zh": "产品/需求描述(必填)"
          },
          "province": {
            "type": "string",
            "description": "Limit to a specific province (optional)",
            "x-description-zh": "限定省份(可选)"
          }
        },
        "required": [
          "product"
        ]
      },
      "RunRequest_discover_buyers": {
        "type": "object",
        "description": "Discover Buyers (10 candidates/search). USD 10 per call. billed from the monthly spTok pool. Single call takes about 9-12 seconds (two LLM calls + database scan); returns the complete result synchronously with no streaming progress.",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "discover.buyers"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_discover_buyers"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 10,
        "x-pooled": true,
        "x-category": "discover",
        "x-name-zh": "发现买家（每次搜索，10个候选）"
      },
      "Payload_discover_suppliers": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string",
            "description": "Product/requirement description (required)",
            "x-description-zh": "产品/需求描述(必填)"
          },
          "province": {
            "type": "string",
            "description": "Limit to a specific province (optional)",
            "x-description-zh": "限定省份(可选)"
          }
        },
        "required": [
          "product"
        ]
      },
      "RunRequest_discover_suppliers": {
        "type": "object",
        "description": "Discover Suppliers (10 candidates/search). USD 10 per call. billed from the monthly spTok pool. Single call takes about 5-8 seconds; returns the complete result synchronously with no streaming progress.",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "discover.suppliers"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_discover_suppliers"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 10,
        "x-pooled": true,
        "x-category": "discover",
        "x-name-zh": "发现供应商（每次搜索，10个候选）"
      },
      "Payload_report_new_product_intelligence": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string",
            "description": "Product/requirement description (required)",
            "x-description-zh": "产品/需求描述(必填)"
          },
          "mode": {
            "type": "string",
            "enum": [
              "design",
              "deconstruct"
            ],
            "default": "design",
            "description": "'design' or 'deconstruct', defaults to 'design'",
            "x-description-zh": "design或deconstruct,默认design"
          }
        },
        "required": [
          "product"
        ]
      },
      "RunRequest_report_new_product_intelligence": {
        "type": "object",
        "description": "New Product Intelligence Report. USD 899 per call. billed standalone via off-session card charge (not pooled). $899 per call, not drawn from the monthly subscription pool (v3.1 rule: anything above $299 is billed standalone). Attempts to charge the account's saved payment method first; if that fails, returns a checkout_url for manual payment confirmation. Takes about 20-40 seconds.",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "report.new_product_intelligence"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_report_new_product_intelligence"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          },
          "async": {
            "type": "boolean",
            "default": false,
            "description": "If true, returns 202 immediately with a job_id instead of waiting for the result. Only this service_code and one other support async — see x-async-capable-services on the /run operation. Charging happens synchronously either way; only the engine run is deferred."
          },
          "callback_url": {
            "type": "string",
            "format": "uri",
            "description": "Optional. Must be https:// and not point at a private/loopback address. When the job finishes, the result is POSTed here (with retries on failure); the job can also be polled at any time via GET /jobs/{job_id} regardless of whether the callback was delivered."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 899,
        "x-pooled": false,
        "x-category": "standalone",
        "x-name-zh": "New Product Intelligence Report",
        "x-async-capable": true
      },
      "Payload_report_target_list_export": {
        "type": "object",
        "properties": {
          "industry": {
            "type": "string",
            "description": "Industry name (required)",
            "x-description-zh": "行业名称(必填)"
          },
          "province": {
            "type": "string",
            "description": "Limit to a specific province (optional)",
            "x-description-zh": "限定省份(可选)"
          },
          "tiers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Restrict to specific tiers, e.g. ['listed','srdi'] (optional)",
            "x-description-zh": "限定档位列表如['listed','srdi'](可选)"
          },
          "min_insured": {
            "type": "integer",
            "minimum": 0,
            "default": 2,
            "description": "Minimum insured-employee threshold, default 2 (optional)",
            "x-description-zh": "最小参保人数门槛,默认2(可选)"
          }
        },
        "required": [
          "industry"
        ]
      },
      "RunRequest_report_target_list_export": {
        "type": "object",
        "description": "Target List Export Report (up to 30). USD 1200 per call. billed standalone via off-session card charge (not pooled). $1200 per call, up to 30 companies with full contact details and a PDF/DOCX/MD/TXT report. Not drawn from the monthly subscription pool -- uses the same off-session charge flow as the New Product Report. Can take 1-3 minutes (includes AI-generated selection rationale and live contact lookup). Returns download_urls; the response body does not include the binary file directly.",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "report.target_list_export"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_report_target_list_export"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          },
          "async": {
            "type": "boolean",
            "default": false,
            "description": "If true, returns 202 immediately with a job_id instead of waiting for the result. Only this service_code and one other support async — see x-async-capable-services on the /run operation. Charging happens synchronously either way; only the engine run is deferred."
          },
          "callback_url": {
            "type": "string",
            "format": "uri",
            "description": "Optional. Must be https:// and not point at a private/loopback address. When the job finishes, the result is POSTed here (with retries on failure); the job can also be polled at any time via GET /jobs/{job_id} regardless of whether the callback was delivered."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 1200,
        "x-pooled": false,
        "x-category": "standalone",
        "x-name-zh": "目标名单导出报告(30家)",
        "x-async-capable": true
      },
      "Payload_report_industry_overview": {
        "type": "object",
        "properties": {
          "industry": {
            "type": "string",
            "description": "Industry name (required)",
            "x-description-zh": "行业名称(必填)"
          },
          "province": {
            "type": "string",
            "description": "Limit to a specific province (optional)",
            "x-description-zh": "限定省份(可选)"
          }
        },
        "required": [
          "industry"
        ]
      },
      "RunRequest_report_industry_overview": {
        "type": "object",
        "description": "China Industry Analysis Report. USD 79 per call. billed from the monthly spTok pool. $79 per call, charged from the standard spTok subscription pool (below the $299 threshold). Returns download_urls for PDF/DOCX/MD/TXT reports. Takes about 10-20 seconds.",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "report.industry_overview"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_report_industry_overview"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 79,
        "x-pooled": true,
        "x-category": "verify",
        "x-name-zh": "中国行业分析报告"
      },
      "Payload_decide_province": {
        "type": "object",
        "properties": {
          "industry": {
            "type": "string",
            "description": "Industry name (required), e.g. 'electronics manufacturing'",
            "x-description-zh": "行业名称(必填,如'电子设备制造')"
          }
        },
        "required": [
          "industry"
        ]
      },
      "RunRequest_decide_province": {
        "type": "object",
        "description": "Province Landing Decision (industry ranking). USD 99 per call. billed from the monthly spTok pool. Given an industry, returns the full density ranking across all 31 provinces (not truncated). The semantics are 'recommend a province to land in for this industry' -- not a lookup of details for a single specific province.",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "decide.province"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_decide_province"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 99,
        "x-pooled": true,
        "x-category": "decide",
        "x-name-zh": "选落地省份决策（行业推荐）"
      },
      "Payload_discover_cn_buyers": {
        "type": "object",
        "properties": {
          "industry": {
            "type": "string",
            "description": "Industry name (required)",
            "x-description-zh": "行业名称(必填)"
          },
          "province": {
            "type": "string",
            "description": "If specified, also returns the buyer company list for that province (optional)",
            "x-description-zh": "若指定,额外返回该省买家企业名录(可选)"
          }
        },
        "required": [
          "industry"
        ]
      },
      "RunRequest_discover_cn_buyers": {
        "type": "object",
        "description": "Discover China Buyers (province/industry list). USD 49 per call. billed from the monthly spTok pool. Returns the full density ranking across all 31 provinces; if province is provided, also returns the buyer company list for that province.",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "discover.cn_buyers"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_discover_cn_buyers"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 49,
        "x-pooled": true,
        "x-category": "discover",
        "x-name-zh": "发现中国买家（按省份/行业清单）"
      },
      "Payload_decide_compare_suppliers_5": {
        "type": "object",
        "properties": {
          "names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 2,
            "maxItems": 5,
            "description": "Array of company full legal names, 2-5 companies (required)",
            "x-description-zh": "企业全称字符串数组,2-5家(必填)"
          }
        },
        "required": [
          "names"
        ]
      },
      "RunRequest_decide_compare_suppliers_5": {
        "type": "object",
        "description": "China Supplier Comparison. USD 149 per call. billed from the monthly spTok pool. Uses the same full_compare() engine as the paid flow on /check/compare on the website, which has been verified in production to complete real payment and delivery end to end.",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "decide.compare_suppliers_5"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_decide_compare_suppliers_5"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 149,
        "x-pooled": true,
        "x-category": "decide",
        "x-name-zh": "中国供应商对比"
      },
      "Payload_discover_competitors": {
        "type": "object",
        "properties": {
          "company": {
            "type": "string",
            "description": "Target company's full legal name (required)",
            "x-description-zh": "目标企业全称(必填)"
          },
          "same_province_only": {
            "type": "boolean",
            "default": false,
            "description": "Whether to limit results to the same province (optional, default false)",
            "x-description-zh": "是否仅限同省(可选,默认false)"
          }
        },
        "required": [
          "company"
        ]
      },
      "RunRequest_discover_competitors": {
        "type": "object",
        "description": "Discover Competitors. USD 29 per call. billed from the monthly spTok pool. Returns the complete list of same-industry competitors, capped at 500 results per call (truncated by score when exceeded; the capped field flags whether truncation occurred).",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "discover.competitors"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_discover_competitors"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 29,
        "x-pooled": true,
        "x-category": "discover",
        "x-name-zh": "发现竞争对手"
      },
      "Payload_decide_market": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string",
            "description": "Product/requirement description (required)",
            "x-description-zh": "产品/需求描述(必填)"
          }
        },
        "required": [
          "product"
        ]
      },
      "RunRequest_decide_market": {
        "type": "object",
        "description": "Overseas Market Selection. USD 29 per call. billed from the monthly spTok pool. Returns the purchaser count ranking across all covered countries (not truncated).",
        "properties": {
          "service_code": {
            "type": "string",
            "const": "decide.market"
          },
          "payload": {
            "$ref": "#/components/schemas/Payload_decide_market"
          },
          "lang": {
            "type": "string",
            "enum": [
              "zh",
              "en"
            ],
            "default": "zh"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Strongly recommended (uuid4). Same key replays the first result and never charges twice."
          }
        },
        "required": [
          "service_code",
          "payload"
        ],
        "x-price-usd": 29,
        "x-pooled": true,
        "x-category": "decide",
        "x-name-zh": "海外市场优选决策"
      },
      "Error": {
        "type": "object",
        "description": "All non-2xx responses carry this shape under FastAPI's `detail` key: {\"detail\": {\"error\": ..., \"msg\": ...}}",
        "properties": {
          "detail": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "enum": [
                  "unknown_service_code",
                  "engine_rejected_input",
                  "checkout_pending",
                  "checkout_invalid",
                  "not_your_checkout",
                  "unknown_checkout_session",
                  "charge_backend_error",
                  "tier_insufficient",
                  "insufficient_sptok",
                  "volume_over_limit",
                  "rate_limited",
                  "engine_error",
                  "not_your_report",
                  "report_not_found",
                  "unknown_report_kind",
                  "bad_fmt",
                  "file_missing",
                  "async_not_supported",
                  "invalid_callback_url",
                  "job_not_found",
                  "not_your_job"
                ]
              },
              "msg": {
                "type": "string"
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": true
          }
        }
      },
      "RunResponsePooled": {
        "type": "object",
        "description": "Success response for pooled services (billed from the spTok pool).",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "service_code": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": true,
            "description": "Engine output; shape depends on service_code."
          },
          "sptok_charged": {
            "type": "integer"
          },
          "price_charged_usd_reference": {
            "type": "number"
          },
          "volume_discount_factor": {
            "type": "number",
            "description": "1.0 / 0.9 / 0.8 by monthly cumulative calls."
          },
          "idempotency_key": {
            "type": "string"
          },
          "replayed": {
            "type": "boolean",
            "description": "true if this idempotency_key was already processed and the original result is returned."
          }
        },
        "required": [
          "ok",
          "service_code",
          "result",
          "sptok_charged",
          "idempotency_key"
        ]
      },
      "RunResponseNonPooled": {
        "type": "object",
        "description": "Success response for non-pooled services (off-session card charge succeeded).",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "service_code": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "usd_charged": {
            "type": "number"
          },
          "payment_intent_id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "service_code",
          "result",
          "usd_charged",
          "payment_intent_id"
        ]
      },
      "OffsessionChargeFailed": {
        "type": "object",
        "description": "Non-pooled service only. HTTP 200 with ok=false: the saved payment method could not be charged automatically. Nothing was run or charged; complete payment at checkout_url.",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string",
            "const": "offsession_charge_failed"
          },
          "reason": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "checkout_url": {
            "type": "string",
            "format": "uri"
          },
          "checkout_session_id": {
            "type": "string",
            "description": "Stripe Checkout session id. Pass to the deliver endpoint after payment."
          },
          "deliver_url": {
            "type": "string",
            "format": "uri",
            "description": "POST here (same Bearer key) after the user completes payment to run the service and get the result."
          },
          "msg": {
            "type": "string"
          }
        },
        "required": [
          "ok",
          "error"
        ]
      },
      "CheckoutDeliverResponse": {
        "type": "object",
        "description": "Result of a non-pooled service paid via checkout_url.",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "service_code": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "usd_charged": {
            "type": "number"
          },
          "paid_via": {
            "type": "string",
            "const": "checkout"
          },
          "checkout_session_id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "service_code",
          "result",
          "idempotency_key"
        ]
      },
      "AsyncJobAccepted": {
        "type": "object",
        "description": "HTTP 202. Charging already happened synchronously (same rules as the sync response); the engine run is deferred to a background job. Poll status_url, or set callback_url on the request to also get a webhook when it finishes.",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "async": {
            "type": "boolean",
            "const": true
          },
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "queued"
          },
          "service_code": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "status_url": {
            "type": "string",
            "format": "uri"
          },
          "usd_charged": {
            "type": "number"
          },
          "payment_intent_id": {
            "type": "string"
          },
          "replayed": {
            "type": "boolean",
            "description": "true if this idempotency_key already has a job; job_id refers to the original job, nothing was re-run or re-charged."
          },
          "callback_secret": {
            "type": "string",
            "description": "Only present when callback_url was set. Shown once — save it. Used to verify the X-SiLink-Signature header on the callback: sha256=hmac_sha256(callback_secret, raw_body)."
          }
        },
        "required": [
          "ok",
          "job_id",
          "status",
          "status_url"
        ]
      },
      "JobStatus": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string"
          },
          "service_code": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "started_at": {
            "type": "string"
          },
          "finished_at": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": true,
            "description": "Present when status=succeeded."
          },
          "error": {
            "type": "object",
            "additionalProperties": true,
            "description": "Present when status=failed. Any charge was refunded."
          },
          "usd_charged": {
            "type": "number"
          },
          "payment_intent_id": {
            "type": "string"
          },
          "callback_status": {
            "type": "string",
            "enum": [
              "none",
              "pending",
              "delivered",
              "failed",
              "exhausted"
            ],
            "description": "Only present if callback_url was set. 'exhausted' means all retries failed — the result itself is still here, only the push notification gave up."
          },
          "callback_attempts": {
            "type": "integer"
          }
        },
        "required": [
          "job_id",
          "service_code",
          "status"
        ]
      },
      "ServicesResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "tier": {
            "type": "string",
            "enum": [
              "business",
              "max"
            ]
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "service_code": {
                  "type": "string"
                },
                "sptok": {
                  "type": "integer"
                },
                "usd": {
                  "type": "number"
                },
                "category": {
                  "type": "string"
                },
                "payload_doc": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "note": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-rate-limits": {
    "window_seconds": 60,
    "per_minute": {
      "max": 60,
      "business": 600
    },
    "scope": "per API key"
  },
  "x-volume-discounts": [
    {
      "lo": 0,
      "hi": 1000,
      "off_pct": 0
    },
    {
      "lo": 1001,
      "hi": 10000,
      "off_pct": 10
    },
    {
      "lo": 10001,
      "hi": 100000,
      "off_pct": 20
    }
  ]
}