API & Embed Docs

Use our public API to search AliExpress products, embed deal banners on your site, build CLI tools, or let AI agents read the humanoid robot catalog. Product responses include affiliate links.

Sub-affiliate earnings: Pass your tag parameter to earn commissions on sales generated through your embeds and API integrations. Sign up for a tag here.

Quick Start — Embed a Banner

Copy this iframe to embed a dynamic product banner on any website:

<iframe
  src="https://bestcartai.com/api/embed?q=wireless+earbuds&tag=YOUR_ID&limit=4&format=html&theme=dark"
  width="100%"
  height="380"
  frameborder="0"
  style="border-radius:12px;"
></iframe>

CLI Usage

Use curl or any HTTP client:

# Search products
curl "https://bestcartai.com/api/products?q=wireless+earbuds&limit=5"

# Read the AI/bot manifest
curl "https://bestcartai.com/ai.json"

# Read the curated robot catalog
curl "https://bestcartai.com/humanoids/catalog.json"

# Read direct robot answers for AI/search
curl "https://bestcartai.com/humanoids/answers"

# Read the Unitree buyer checklist
curl "https://bestcartai.com/humanoids/buyer-checklist"

# Use OpenAPI with generators or agent tooling
curl "https://bestcartai.com/openapi.json"

# AI chat
curl -X POST https://bestcartai.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"best phone case under $10","timestamp":0}]}'

# Visual search
curl -X POST https://bestcartai.com/api/visual-search \
  -F "image=@product-photo.jpg"

# Get embed JSON for your site
curl "https://bestcartai.com/api/embed?q=led+lights&tag=my_blog&format=json"

API Endpoints

GET/ai.json

Compact machine-readable site manifest for bots, answer engines, and CLIs

Param	Type	Description

Example:

curl https://bestcartai.com/ai.json

GET/openapi.json

OpenAPI 3.1 schema for public BestCart AI endpoints

Param	Type	Description

Example:

curl https://bestcartai.com/openapi.json

GET/humanoids/catalog.json

Curated Unitree and humanoid robot catalog with SDK/EDU development notes

Param	Type	Description

Example:

curl https://bestcartai.com/humanoids/catalog.json

GET/humanoids/answers

Crawlable robot Q&A with FAQPage structured data for search and AI answer engines

Param	Type	Description

Example:

curl https://bestcartai.com/humanoids/answers

GET/humanoids/buyer-checklist

Crawlable seller-message templates and quote checklist for high-ticket Unitree buyers

Param	Type	Description

Example:

curl https://bestcartai.com/humanoids/buyer-checklist

GET/api/products

Search AliExpress products with affiliate links

Param	Type	Description
`q`	string	Search query (e.g. 'wireless earbuds')
`limit`	number	Results per page (max 50, default 40)
`offset`	number	Pagination offset
`sort`	string	relevance \| price_asc \| price_desc \| newest
`min_price`	number	Minimum price filter
`max_price`	number	Maximum price filter
`currency`	string	Target currency (USD, EUR, GBP, etc.)
`country`	string	Ship-to country code (US, DE, BR, etc.)
`category_id`	string	AliExpress category ID

Example:

/api/products?q=wireless+earbuds&limit=5&currency=EUR&sort=price_asc

POST/api/chat

AI shopping assistant — conversational product search

Param	Type	Description
`messages`	array	[{"role":"user","content":"...","timestamp":123}]

Example:

{"messages":[{"role":"user","content":"best bluetooth speaker under $20","timestamp":1234}]}

POST/api/visual-search

Upload an image, AI identifies the product and finds it on AliExpress

Param	Type	Description
`image`	File	Image file (multipart/form-data)

Example:

curl -X POST -F 'image=@photo.jpg' https://bestcartai.com/api/visual-search

POST/api/subscribe

Capture robot buyer intent for EDU quotes, price drops, accessories, and buying help

Param	Type	Description
`email`	string	Buyer email address
`interest`	string	edu-quote \| price-drop \| accessories \| buying-help
`productSlug`	string	Optional robot slug such as unitree-g1
`currentPrice`	number	Optional current price for price-drop scoring
`targetPrice`	number	Optional target alert price
`targetDropPct`	number	Optional target discount percentage
`source`	string	Where the lead came from

Example:

curl -X POST https://bestcartai.com/api/subscribe -H "Content-Type: application/json" -d '{"email":"buyer@example.com","interest":"price-drop","productSlug":"unitree-g1","currentPrice":18852,"targetDropPct":10}'

GET/api/embed

Embeddable product banner — returns HTML or JSON for publishers

Param	Type	Description
`q`	string	Search query
`tag`	string	Your sub-affiliate tracking ID
`limit`	number	Number of products (max 12)
`format`	string	json \| html (default: json)
`currency`	string	Target currency
`theme`	string	dark \| light

Example:

/api/embed?q=phone+cases&tag=my_blog&limit=4&format=html&theme=dark

GET/api/og

Dynamic Open Graph image for social sharing

Param	Type	Description
`title`	string	Product title
`price`	string	Sale price
`original`	string	Original price
`discount`	string	Discount percentage
`image`	string	Product image URL

Example:

/api/og?title=Wireless+Earbuds&price=7.22&original=14.73&discount=51

Rate Limits

Product search: 50 requests/minute per IP

Chat: 20 requests/minute per IP

Visual search: 10 requests/minute per IP

Embed: 100 requests/minute per IP (cached for 5 min)