{
  "openapi": "3.0.1",
  "info": {
    "title": "1688 Supplier Finder — Bulk Supplier Shortlist & Comparison",
    "description": "Compare 1688 suppliers across your whole product list: a ranked, deduplicated shortlist per product with prices, MOQ and estimated landed cost, plus a free rollup of the suppliers that cover several of your SKUs.",
    "version": "0.1",
    "x-build-id": "apO1D04tQdgtXtT1c"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/crawleast~1688-supplier-finder/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-crawleast-1688-supplier-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/crawleast~1688-supplier-finder/runs": {
      "post": {
        "operationId": "runs-sync-crawleast-1688-supplier-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/crawleast~1688-supplier-finder/run-sync": {
      "post": {
        "operationId": "run-sync-crawleast-1688-supplier-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "products": {
            "title": "Products",
            "type": "array",
            "description": "Up to 100 products per run. Each product requires imageUrl: a public http(s) photo URL without credentials, up to 2048 characters. Optional title (up to 200 characters), asin (up to 32 characters) and clientSku (up to 64 characters) are echoed as labels for joining to your sheet. Title-only searching is not supported. Entries without a usable imageUrl are INVALID_PRODUCT and never charged. Lists over 100 entries return INPUT_TOO_LONG before searching and are never charged; split them across runs. The validated default is 5 offers per product with 1 enriched offer, not a guarantee that every image has a match."
          },
          "productsCsv": {
            "title": "Products as CSV (alternative)",
            "type": "string",
            "description": "Paste a raw CSV export (up to 2 MB and 100 data rows) instead of products. More rows are rejected before searching, never silently truncated. A header and an image URL column are required: image, image_url, imageUrl, img or image url. Optional label columns: title/name/product/product_name/product name, asin, and sku/clientSku/client_sku/id. Column names are case-insensitive. Missing image columns, duplicate aliases or malformed CSV return CSV_PARSE_FAILED with detected columns. Title-only search is unsupported. Ignored when products is filled in."
          },
          "shortlistSize": {
            "title": "Suppliers per product",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many supplier offers to return per product (rows per product).",
            "default": 5
          },
          "enrichDepth": {
            "title": "Enriched suppliers per product",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "How many of the top shortlisted offers per product get a detail-page enrichment (price ladder, weight, estimated landed cost, margin, dropship score, compliance hints). Leave empty to follow \"Enrich top supplier\" (1 when on, 0 when off). 0 = list-level rows only. Values above Suppliers per product are reduced to it. Products × this value may not exceed 400 per run."
          },
          "enrichDetails": {
            "title": "Enrich top supplier",
            "type": "boolean",
            "description": "Used only when Enriched suppliers per product is empty: on = enrich the top 1 offer per product, off = no enrichment.",
            "default": true
          },
          "maxResultsPerProduct": {
            "title": "Candidate pool per product",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many 1688 search results per product are considered before sorting, de-duplication and the shortlist cut.",
            "default": 20
          },
          "targetMarket": {
            "title": "Target market",
            "enum": [
              "US",
              "EU",
              "UK",
              "AU",
              "global"
            ],
            "type": "string",
            "description": "Destination market used for the estimated landed cost (duty rate) and compliance hints on enriched rows.",
            "default": "US"
          },
          "sortBy": {
            "title": "Sort shortlist by",
            "enum": [
              "landedCost",
              "price",
              "supplierYears",
              "matchScore",
              "supplierCoverage"
            ],
            "type": "string",
            "description": "Ranking of each product's shortlist. landedCost: enriched rows with an estimated landed cost first (cheapest first), then the rest by unit price; with no enrichment it falls back to unit price. Costs use the MOQ-applicable tier price, not the lowest bulk-quantity price; landedCostBasis and unitWeightBasis distinguish a source-linked SKU from a representative/inferred-weight rough estimate. price: lowest unit price first. supplierYears: longest on 1688 first. matchScore: 1688 result order. supplierCoverage: suppliers that also appear for more of your other products first, then price.",
            "default": "landedCost"
          },
          "minMatchScore": {
            "title": "Minimum match score",
            "minimum": 0,
            "maximum": 1,
            "type": "number",
            "description": "Drop candidates below this matchScore (0–1). matchScore is a relative position score from the 1688 result order (1 = first result), not a visual-similarity percentage. 0 keeps every candidate.",
            "default": 0
          },
          "supplierDedupe": {
            "title": "One offer per supplier",
            "type": "boolean",
            "description": "Keep only the best-ranked offer of each identified company within a product's shortlist. Offers without reliable corporate identity cannot be deduplicated by supplier.",
            "default": true
          },
          "excludeSupplierIds": {
            "title": "Exclude suppliers",
            "type": "array",
            "description": "Supplier companyId values (from a previous run's companyId column) to leave out of every shortlist. Up to 1000.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "maxTotalChargeUsd": {
            "title": "Max charge budget (USD)",
            "minimum": 0.04,
            "type": "number",
            "description": "Hard cap on pay-per-event charges for this run. Events: run-base-fee $0.01 once per run, only when at least one row is delivered; product-matched $0.010 per product that delivers at least one row; shortlist-row $0.003 per delivered row; supplier-enriched $0.002 per delivered enriched row. Products the cap cannot cover are skipped before searching (SKIPPED_QUOTA) and never charged; everything already delivered is kept. Failed, unmatched or skipped products are never charged.",
            "default": 20
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}