Search
Search products or resolve a pasted marketplace link.
GET /api/v1/search requires a bearer token. It uses the same search decision as the storefront and app, without writing customer or visit history.
curl --get https://www.ninjabuy.com/api/v1/search \
-H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
--data-urlencode "q=hoodie" \
--data-urlencode "provider=taobao" \
--data-urlencode "page=0"Query parameters
| Parameter | Rules |
|---|---|
q | Required, trimmed. Keywords: 2 to 120 characters. Pasted links: up to 2,048 characters. |
provider | taobao (default) or a1688. |
page | Zero-based integer from 0 to 20; default 0. |
Send each parameter once. Invalid or repeated parameters return 400 with the bad-body problem.
Answer kinds
Every successful answer has kind and request_id.
kind | Fields and meaning |
|---|---|
products | Keyword results: items, page, pageSize, totalCount, maximumPageCount, and unread (a host object for an unread paste, otherwise null). |
product | One product: handle and storefront url. A pasted link or an item-id search can resolve directly to this kind. |
vendor | A resolved shop: vendor. |
sheet | A recognized Google Sheet: sheetId and nullable gid; no sheet contents. |
unsupported | A recognized unsupported link: link containing marketplace and id. |
Each item in products contains handle, storefront url, title, price: { amount, currency: "CNY" }, nullable image, and marketplace (taobao or a1688). amount is a decimal string in Chinese yuan, matching the storefront grid. Search URLs are ordinary product URLs; use Links to create credited links.
Spend and rate limits
Pasted links use the anonymous resolver and cannot buy a paid Bright Data unblocker. Recognized product, vendor, sheet and unsupported links skip keyword search. An unread paste can fall through to keyword search and spend OT search quota.
Keyword searches have their own limit of 30 calls per account per 60 seconds, separate from create-links calls. Successful responses that reach keyword admission and search rate-limit refusals carry:
RateLimit-Policy: "search";q=30;w=60
RateLimit: "search";r=29;t=60A refusal returns 429, the search-rate-limited problem and Retry-After in seconds. Resolved pastes consume neither window and do not carry search rate headers. Every response carries X-Request-Id and Cache-Control: no-store. See Rate limits for header fields.