Catalog API

New

Bring your own products. Upload your catalog, we generate the embeddings, and you can search by visual similarity across your entire inventory in under 50ms.

Overview

The Catalog API enables you to:

Upload products — Single or batch upload with automatic embedding generation
Search visually — Find similar products by image in your own catalog
Full feature extraction — CLIP, silhouette, colors, and attributes automatically extracted
Scale as needed — From 1,000 to 100,000+ products depending on your tier

Endpoints

Endpoint	Description
POST /v1/catalog/products	Upload products (single or batch)
GET /v1/catalog/products	List products with pagination
GET /v1/catalog/products/:id	Get a single product
DELETE /v1/catalog/products/:id	Delete a product
POST /v1/catalog/search	Search by image similarity

Upload Products

Single Product Upload

curl -X POST https://www.dupifyapp.com/v1/catalog/products \

-H "X-API-Key: YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{

"title": "Classic Black Leather Jacket",

"image_url": "https://example.com/jacket.jpg",

"external_id": "SKU-12345",

"price": 299.99,

"category": "Outerwear"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "SKU-12345",
  "status": "created",
  "embedding_status": "processing"
}

Batch Upload

Upload multiple products in a single request. Batch size limits vary by tier.

curl -X POST https://www.dupifyapp.com/v1/catalog/products \

-H "X-API-Key: YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{"products": [...]}'

Product Fields

Field	Type	Required	Description
title	string	Yes	Product title
image_url	string	Yes	URL to product image
external_id	string	No	Your product ID (for upsert)
sku	string	No	Product SKU
description	string	No	Product description
brand	string	No	Brand name
category	string	No	Product category
price	number	No	Price amount
currency	string	No	Currency code (default: USD)
product_url	string	No	Link to product page
metadata	object	No	Custom key-value data

Search by Image

Find visually similar products in your catalog using an image URL or base64-encoded image.

curl -X POST https://www.dupifyapp.com/v1/catalog/search \

-H "X-API-Key: YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{"image_url": "https://example.com/query.jpg"}'

Response

{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "SKU-12345",
      "title": "Classic Black Leather Jacket",
      "image_url": "https://example.com/jacket.jpg",
      "price": 299.99,
      "similarity_score": 0.94
    },
    ...
  ],
  "query": {
    "type": "image"
  },
  "total_found": 15,
  "processing_time_ms": 42
}

Search Options

Field	Type	Description
image_url	string	URL of image to search with
image_base64	string	Base64-encoded image data
product_id	string	Find similar to existing product
max_results	number	Max results (default: 20)
similarity_threshold	number	Min similarity (default: 0.70)
category	string	Filter by category
min_price	number	Minimum price filter
max_price	number	Maximum price filter

Tier Limits

Tier	Max Products	Searches/Month	Batch Size
Free	1,000	500	10
Starter	10,000	5,000	50
Pro	100,000	50,000	100
Unlimited	No limit	No limit	100

Best Practices

Use external_id — Enables upsert behavior; re-uploading updates the existing product
Wait for embeddings — Products become searchable after embedding_status: completed
Use high-quality images — Clear product images yield better similarity results
Add metadata — Store custom fields in metadata for filtering in your app
Batch uploads — Use batch endpoint for bulk imports to reduce API calls

Pro tip: The embedding generation happens asynchronously. Poll the product endpoint or use a webhook (coming soon) to know when embeddings are ready.

Embedding Status

After uploading, products go through embedding generation:

Status	Description
pending	Queued for processing
processing	Generating embeddings
completed	Ready for search
failed	Error occurred (check embedding_error)

← API Reference Rate Limits →