Qualit.ly
Qualit.ly
HomeDiscord BotAI Chat

API Reference

Qualit.ly API

Product data, QC images, and metadata from Weidian, Taobao, and 1688. Bearer token auth, generous rate limits, tiered plans.

Get API Key

Getting Started

All requests go to https://backend.qualit.ly/api/v1. Three steps:

1

Get a key

Sign in and create an API key from the developer dashboard.

2

Make a request

Send your key as a Bearer token in the Authorization header.

3

Get data

Receive JSON responses with product data and QC images.

Quick example

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/weidian/1234567890

Authentication

Include a valid API key in the Authorization header using the Bearer scheme.

Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Key format

Keys follow qc_{mode}_{random} where mode is live or test, and random is 32 cryptographically random characters.

Keys are shown once at creation. We store only the SHA-256 hash — lost keys cannot be recovered.

IP allowlisting

Optionally restrict keys to specific IPs or CIDR ranges via the developer dashboard. Requests from unlisted IPs get a 403. An empty allowlist allows all IPs.

Rate Limits

Two buckets: per-minute and per-month. Limits are tied to your account tier and apply across all keys.

Tier
/ minute
/ month
Basic
30
1,000
Early Adopter
40
3,000
Pro
300
25,000
Pro+
1,000
500,000

When rate limited

The API returns 429 with a Retry-After header.

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Per-minute limit exceeded",
    "retry_after": 12
  }
}

Errors

All errors return a top-level error object with code and message.

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}
401UNAUTHORIZEDMissing or invalid API key.
403FORBIDDENYour tier lacks access, or IP is blocked.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDQuota exceeded — check Retry-After header.
400BAD_REQUESTInvalid request body or parameters.
500INTERNALServer error. Retry or contact support.

Endpoints

Base: https://backend.qualit.ly/api/v1. Storefronts: weidian, taobao, 1688.

GET/products/:storefront/:listingIdBasic

Look up a single product by storefront and listing ID. Returns metadata and up to 5 QC preview thumbnails.

Parameters

storefrontrequired

One of: weidian, taobao, 1688

listingIdrequired

The product listing ID from the storefront

Example

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/weidian/7231368393

Response

json
{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "name": "AJ1 Retro High OG",
    "price": "¥470.00",
    "pic_url": "https://cdn.qualit.ly/covers/...",
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qc_count": 12,
    "qc_preview": [
      "https://cdn.qualit.ly/qc/...",
      "https://cdn.qualit.ly/qc/..."
    ]
  }
}
POST/products/batchPro+

Look up multiple products in a single request (up to 100). Each result is independent — a missing product won't fail the batch.

Request body

json
{
  "items": [
    { "storefront": "weidian", "listing_id": "7231368393" },
    { "storefront": "taobao", "listing_id": "123456789" }
  ]
}

Example

bash
curl -X POST \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"storefront":"weidian","listing_id":"7231368393"}]}' \
  https://backend.qualit.ly/api/v1/products/batch

Response

json
{
  "results": [
    {
      "data": {
        "id": 482910,
        "storefront": "weidian",
        "listing_id": "7231368393",
        "name": "AJ1 Retro High OG",
        "price": "¥470.00",
        "qc_count": 12,
        "qc_preview": ["..."]
      }
    },
    { "error": { "code": "NOT_FOUND" } }
  ]
}
GET/qc/:storefront/:listingIdBasic

Get QC metadata and the first 3 thumbnail image URLs for a product.

Example

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/weidian/7231368393
json
{
  "data": {
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qc_count": 12,
    "thumbnails": ["..."]
  }
}
GET/qc/:id/imagesPro+

Full list of QC images. Accepts a numeric product ID or a ?url= query parameter for URL-based lookups.

By product ID

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/482910/images

By URL

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  "https://backend.qualit.ly/api/v1/qc/0/images?url=https://weidian.com/item.html?itemID=7231368393"

Response

json
{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qc_count": 12,
    "images": [
      "https://cdn.qualit.ly/qc/img1.jpg",
      "https://cdn.qualit.ly/qc/img2.jpg",
      "..."
    ]
  }
}
Pro+ only. The ?url= param accepts full product URLs from Weidian, Taobao, 1688, and supported agents.
GET/meBasic

Returns your account info, the key used for the request, and your current tier.

Example

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/me
json
{
  "user": { "id": 12345, "username": "you" },
  "key": { "id": 1, "mode": "live" },
  "tier": "basic"
}
GET/usageBasic

Check your current rate-limit and quota usage. Returns per-minute and per-month counters with reset timestamps. The call itself consumes 1 request from both counters.

Example

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/usage

Response

json
{
  "tier": "pro_plus",
  "key": { "id": 7, "mode": "live" },
  "minute": {
    "limit": 1000,
    "used": 12,
    "remaining": 988,
    "reset_in_seconds": 37,
    "reset_at": "2026-04-17T18:42:00.000Z"
  },
  "month": {
    "limit": 500000,
    "used": 1843,
    "remaining": 498157,
    "reset_in_seconds": 1159200,
    "reset_at": "2026-05-01T00:00:00.000Z",
    "bucket": 202604
  }
}

Fields

tier

One of: basic, early_adopter, pro, pro_plus, custom

limit / remaining

null on the custom tier (unlimited)

used

Requests counted in the current window. Minute counter resets every 60s; month counter resets at UTC month rollover.

reset_at

ISO 8601 UTC timestamp

bucket

Internal YYYYMM key for the month counter

Errors

Same as other /api/v1/* routes:401 INVALID_KEY /REVOKED_KEY,403 IP_NOT_AUTHORIZED,429 RATE_LIMITED /QUOTA_EXCEEDED.

Code Samples

Quick-start snippets in popular languages.

const res = await fetch(
  'https://backend.qualit.ly/api/v1/products/weidian/7231368393',
  { headers: { Authorization: 'Bearer ' + process.env.QUALITLY_KEY } }
);
const { data } = await res.json();
console.log(data.name, data.qc_count, 'QC images');

Plans & Tiers

Your tier is resolved on every request — upgrades take effect immediately. Batch and full-image endpoints require Pro+.

Plan
/ minute
/ month
Batch + Images
Basic
30
1,000
—
Early Adopter
40
3,000
—
Pro
300
25,000
—
Pro+
1,000
500,000
Included

Need higher limits? [email protected]

Qualit.ly

Free QC photos, Discord link converter and AI haul builder for Taobao, Weidian and 1688.

Tools

  • Search QC photos
  • Discord link converter
  • AI haul chat
  • Order tracking
  • Public REST API

Marketplaces

  • Weidian QC photos
  • Taobao QC photos
  • 1688 QC photos

Resources

  • About Qualit.ly
  • Contact
  • Discord community
  • r/qualitly
  • Telegram channel

© Qualit.ly. Free for the rep finds community.

Questions? [email protected]