Links
Request fields, per-link results and repeat requests.
Create links
POST https://www.ninjabuy.com/api/v1/links requires a bearer token and Content-Type: application/json.
| Field | Rules |
|---|---|
links | Required array of 1 to 2,000 strings. Each input is trimmed and must be 1 to 4,096 characters. |
campaign | Optional, 3 to 64 lowercase letters, digits or hyphens, starting with a letter or digit: ^[a-z0-9][a-z0-9-]{2,63}$. Visits carry it as utm_campaign. |
label | Optional name on your links list: 1 to 40 printable characters after trimming, with no control characters. Trimming produces a warning. |
async | Optional boolean. true always starts a background job. |
Product links from Taobao, Tmall, Weidian and 1688, supported shopping-agent links and short links, Weidian and Taobao shops (including a supported agent's page for one), and supported public NinjaBuy pages can be converted. A NinjaBuy URL or bare path such as /search?q=hoodie is accepted. Pasting an existing NinjaBuy referral link makes your own credited link to its target.
Inline or batch
Up to 100 inputs without async: true return 200 with results, warnings and request_id. More than 100, or async: true, return 202 with a job, Location and Retry-After. See Quickstart and Jobs.
Results preserve input order, including repeated inputs. Each row has input and status, with optional target, url, code and note.
| Status | Meaning |
|---|---|
ok | Converted; url is the credited NinjaBuy link. |
unsupported | Recognized but cannot be linked, such as an unsupported marketplace or private NinjaBuy page. |
unreadable | No usable target could be read. |
sheet | A Google Sheet URL; this endpoint does not convert its contents. |
For a sheet, use the Sheets API to convert its contents to XLSX, or paste it on NinjaBuy. An existing NinjaBuy /spreadsheets/d/<sheet id> page can itself receive a credited link.
Repeat requests and attribution
For the same account, normalized target, campaign and label, minting returns the same link across REST, MCP and batch processing. A different campaign or label gets a separate link. Without an Idempotency-Key, retrying a batch still creates a new job; link reuse does not deduplicate job submissions.
New REST links record createdVia: "api". Reusing a link preserves its original source (api, mcp, share or redirect). This field is available in MCP list_links and link results, not the REST create response. See Referrals for credit and reporting.
Idempotency-Key
Optionally send Idempotency-Key on POST /api/v1/links, POST /api/v1/uploads or POST /api/v1/sheets to retry a request without creating another job or consuming another create-links slot. Use a unique key for each intended request: 1 to 255 printable ASCII characters.
Idempotency-Key: partner-batch-2026-10-23-001For 24 hours, the same account, key and validated request replay the original status, byte-identical body and headers, including the original request_id, with Idempotent-Replayed: true. JSON object key order does not matter. After 24 hours the key can be reused.
- A different body or POST route with the same key returns
422(idempotency-key-reused); use a new key. - While the first request is running, retries return
409(idempotency-key-in-progress) withRetry-After; wait before retrying. - An invalid key returns
400(bad-idempotency-key). Invalid bodies do not reserve a key. - Once execution starts, its first answer is stored, including errors. A
429is not stored: retry with the same key afterRetry-After.
A crashed request can stay in progress until the key expires. This request replay is separate from matching-link reuse above.