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:

Get a key

Make a request

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

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, so 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

1,000

Early Adopter

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"
  }
}

400BAD_REQUESTInvalid request body or parameters.

401INVALID_KEYMissing, malformed, or unknown API key.

401REVOKED_KEYThe API key was revoked in the dashboard.

403IP_NOT_AUTHORIZEDRequest IP is not in the key’s allowlist.

403FORBIDDENYour tier lacks access to this endpoint.

404NOT_FOUNDThe requested resource does not exist.

429RATE_LIMITEDPer-minute limit exceeded, check Retry-After.

429QUOTA_EXCEEDEDMonthly quota exhausted; resets at UTC month rollover.

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, so 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');

MCP Server

The Qualit.ly API is available as a Model Context Protocol (MCP) server. Connect it to Claude Desktop, Cursor, VS Code, or any MCP-compatible client and query products, QC images, and usage data directly from your AI assistant, with no manual HTTP needed. The same API key, rate limits, and tier rules apply.

Server URL

https://backend.qualit.ly/api/mcp

Transport

StreamableHTTP (POST)

Auth

Authorization: Bearer qc_live_…

Available tools

Tool

Description

Tier

get_product

Look up a product by storefront and listing ID

Basic

get_products_batch

Look up up to 100 products in one call

Pro+

get_qc

QC count and 3 thumbnail URLs

Basic

get_qc_images

Full CDN image list (by ID or URL)

Pro+

get_me

Current key, user, and tier

Basic

get_usage

Per-minute and monthly quota status

Basic

OAuth 2.0 supported. Clients that support OAuth auto-discovery (Claude.ai, ChatGPT, etc.) will automatically prompt your users to authorize via a login page, with no hardcoded key needed. The server advertises its OAuth endpoints at https://backend.qualit.ly/.well-known/oauth-authorization-server.

Claude Desktop (hardcoded key)

Add this to your claude_desktop_config.json (Claude → Settings → Developer):

json

{
  "mcpServers": {
    "qualitly": {
      "url": "https://backend.qualit.ly/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor / VS Code (hardcoded key)

json

{
  "mcp": {
    "servers": {
      "qualitly": {
        "url": "https://backend.qualit.ly/api/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

Quick verification

bash

# List available tools
curl -X POST https://backend.qualit.ly/api/mcp \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Plans & Tiers

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

Plan

/ minute

/ month

Batch + Images

Basic

1,000

—

Early Adopter

3,000

—

Pro

300

25,000

—

Pro+

1,000

500,000

Included

Need higher limits? [email protected]

See full plans, pricing & perks

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:

Get a key

Make a request

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

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, so 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

1,000

Early Adopter

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"
  }
}

400BAD_REQUESTInvalid request body or parameters.

401INVALID_KEYMissing, malformed, or unknown API key.

401REVOKED_KEYThe API key was revoked in the dashboard.

403IP_NOT_AUTHORIZEDRequest IP is not in the key’s allowlist.

403FORBIDDENYour tier lacks access to this endpoint.

404NOT_FOUNDThe requested resource does not exist.

429RATE_LIMITEDPer-minute limit exceeded, check Retry-After.

429QUOTA_EXCEEDEDMonthly quota exhausted; resets at UTC month rollover.

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, so 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');

MCP Server

Server URL

https://backend.qualit.ly/api/mcp

Transport

StreamableHTTP (POST)

Auth

Authorization: Bearer qc_live_…

Available tools

Tool

Description

Tier

get_product

Look up a product by storefront and listing ID

Basic

get_products_batch

Look up up to 100 products in one call

Pro+

get_qc

QC count and 3 thumbnail URLs

Basic

get_qc_images

Full CDN image list (by ID or URL)

Pro+

get_me

Current key, user, and tier

Basic

get_usage

Per-minute and monthly quota status

Basic

Claude Desktop (hardcoded key)

Add this to your claude_desktop_config.json (Claude → Settings → Developer):

json

{
  "mcpServers": {
    "qualitly": {
      "url": "https://backend.qualit.ly/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor / VS Code (hardcoded key)

json

{
  "mcp": {
    "servers": {
      "qualitly": {
        "url": "https://backend.qualit.ly/api/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

Quick verification

bash

# List available tools
curl -X POST https://backend.qualit.ly/api/mcp \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Plans & Tiers

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

Plan

/ minute

/ month

Batch + Images

Basic

1,000

—

Early Adopter

3,000

—

Pro

300

25,000

—

Pro+

1,000

500,000

Included

Need higher limits? [email protected]

See full plans, pricing & perks