Channel3 API Integration Guide

You are helping a developer integrate with the Channel3 API. This guide contains everything you need to write correct, working integration code.

Quick Orientation

Channel3 provides a universal product catalog API. Developers use it to search products, get product details, enrich URLs, track prices, and look up brands/websites. Every product link includes affiliate tracking, so developers earn commission on sales they drive.

Base URL: https://api.trychannel3.com/v0 Auth: x-api-key header (or SDK client initialization with apiKey) Docs: https://docs.trychannel3.com

Before Writing Code

1. Read references/api-reference.md for the full endpoint and type reference — it has every parameter, type, and response shape you’ll need.
2. Ask the developer which language they’re using (TypeScript, Python, or raw HTTP/curl) if it’s not obvious from context.
3. If the developer hasn’t set up their API key yet, show them how to get one at https://trychannel3.com and configure it as an environment variable (CHANNEL3_API_KEY).

SDK Installation

TypeScript:

npm install @channel3/sdk

Python:

pip install channel3_sdk

Client Initialization

TypeScript:

import Channel3 from '@channel3/sdk';

const client = new Channel3({
  apiKey: process.env['CHANNEL3_API_KEY'],
});

Python (sync):

import os
from channel3_sdk import Channel3

client = Channel3(api_key=os.environ.get("CHANNEL3_API_KEY"))

Python (async):

import os
from channel3_sdk import AsyncChannel3

client = AsyncChannel3(api_key=os.environ.get("CHANNEL3_API_KEY"))

curl:

curl -X POST https://api.trychannel3.com/v0/search \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "wireless headphones", "limit": 5}'

Core Endpoints

1. Product Search (POST /v0/search)

This is the primary endpoint. It supports text queries, image search (via URL or base64), and rich filtering. Returns an array of Product objects.

Key parameters:

• query — natural language or keywords
• image_url / base64_image — for visual search (find visually similar products)
• filters — price range, brand, category, gender, age, condition, availability, website
• context — personalization context (e.g., “looking for a gift for a 30-year-old who likes hiking”)
• limit — 1-30 results (default 20)
• config.redirect_mode — controls affiliate link routing: "price" (cheapest), "commission" (highest commission), or "brand" (brand page)
• config.keyword_search_only — disable semantic search, use exact keyword matching only

Example — TypeScript:

const products = await client.search.perform({
  query: 'running shoes under $100',
  filters: {
    price: { max_price: 100 },
    gender: 'male',
    condition: 'new',
  },
  limit: 10,
  config: { redirect_mode: 'price' },
});

for (const product of products) {
  console.log(`${product.title} - $${product.price.price} ${product.price.currency}`);
  console.log(`  Buy: ${product.url}`);
}

Example — Python:

products = client.search.perform(
    query="running shoes under $100",
    filters={
        "price": {"max_price": 100},
        "gender": "male",
        "condition": "new",
    },
    limit=10,
    config={"redirect_mode": "price"},
)

for product in products:
    print(f"{product.title} - ${product.price.price} {product.price.currency}")
    print(f"  Buy: {product.url}")

Example — curl:

curl -X POST https://api.trychannel3.com/v0/search \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "running shoes under $100",
    "filters": {
      "price": {"max_price": 100},
      "gender": "male",
      "condition": "new"
    },
    "limit": 10,
    "config": {"redirect_mode": "price"}
  }'

2. Product Details (GET /v0/products/{product_id})

Retrieve full details for a specific product by ID. Returns a ProductDetail object with images, variants, key features, materials, and more.

Example — TypeScript:

const detail = await client.products.retrieve('prod_abc123', {
  redirect_mode: 'price',
});
console.log(detail.title, detail.description);
console.log('Variants:', detail.variants?.map(v => v.title));

3. URL Enrichment (POST /v0/enrich)

Given a product page URL, returns structured product data from Channel3’s catalog. If the product isn’t already indexed, it attempts real-time extraction with basic details (price, images, title).

Example — Python:

detail = client.enrich.enrich_url(url="https://example.com/product/cool-sneakers")
print(detail.title, detail.price.price)

4. Price Tracking (/v0/price-tracking/...)

Subscribe to price changes on products, retrieve price history (up to 30 days), and manage subscriptions.

• client.priceTracking.start({ canonical_product_id }) — start tracking
• client.priceTracking.stop({ canonical_product_id }) — stop tracking
• client.priceTracking.getHistory(id, { days }) — get price history with statistics
• client.priceTracking.listSubscriptions() — list active subscriptions

The history response includes statistics: current price, min/max, mean, standard deviation, and a current_status indicator ("low", "typical", or "high").

5. Brands (GET /v0/list-brands, GET /v0/brands)

• client.brands.list({ limit, paging_token }) — paginated alphabetical list (1-100 per page)
• client.brands.find({ query: 'Nike' }) — find a brand by name

Each brand includes id, name, optional description, logo_url, and best_commission_rate.

6. Websites (GET /v0/websites)

• client.websites.find({ query: 'amazon.com' }) — look up a retailer website

Returns id, url, and best_commission_rate. Useful for filtering search results to specific retailers.

Error Handling

Both SDKs throw typed errors. Always handle at least AuthenticationError (401) and RateLimitError (429).

TypeScript:

import Channel3 from '@channel3/sdk';

try {
  const products = await client.search.perform({ query: 'laptop' });
} catch (err) {
  if (err instanceof Channel3.AuthenticationError) {
    console.error('Invalid API key');
  } else if (err instanceof Channel3.RateLimitError) {
    console.error('Rate limited — slow down or upgrade your plan');
  } else if (err instanceof Channel3.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
  }
}

Python:

from channel3_sdk import AuthenticationError, RateLimitError, APIStatusError

try:
    products = client.search.perform(query="laptop")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limited — slow down or upgrade your plan")
except APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")

SDK Configuration

Both SDKs support:

• Retries: Default 2 automatic retries on connection errors, 408, 409, 429, and 5xx. Configure with maxRetries (TS) / max_retries (Python).
• Timeouts: Default 60 seconds. Configure with timeout parameter.
• Logging: Set logLevel: 'debug' (TS) or CHANNEL3_LOG=debug env var (Python) for request/response logging.

Common Patterns

Image-Based Search (Visual Similarity)

// Search by image URL
const similar = await client.search.perform({
  image_url: 'https://example.com/photo-of-dress.jpg',
  limit: 10,
});

// Or by base64 image
const similar = await client.search.perform({
  base64_image: base64EncodedImageString,
  limit: 10,
});

Combining Text + Image Search

const results = await client.search.perform({
  query: 'similar but in blue',
  image_url: 'https://example.com/red-jacket.jpg',
  limit: 10,
});

Personalized Search with Context

const results = await client.search.perform({
  query: 'birthday gift',
  context: 'Shopping for a 28-year-old woman who loves outdoor activities and sustainable brands',
  limit: 15,
});

Filtering to Specific Retailers

// First, find the website ID
const amazon = await client.websites.find({ query: 'amazon.com' });

// Then filter search results
const results = await client.search.perform({
  query: 'wireless earbuds',
  filters: { website_ids: [amazon.id] },
});

Price Drop Monitoring

// Start tracking
await client.priceTracking.start({
  canonical_product_id: 'prod_abc123',
});

// Check history later
const history = await client.priceTracking.getHistory('prod_abc123', { days: 30 });
console.log(`Current: $${history.statistics?.current_price} (${history.statistics?.current_status})`);
console.log(`30-day range: $${history.statistics?.min_price} - $${history.statistics?.max_price}`);

Important Notes

• The url field on every product is an affiliate-tracked link. Using these links means the developer earns commission on any resulting sales — no extra setup required.
• redirect_mode controls where the affiliate link points: "price" finds the cheapest option, "commission" maximizes the developer’s earnings, and "brand" goes to the brand’s own site.
• Image search and text search can be combined. When both query and image_url/base64_image are provided, the API performs a multimodal search.
• config.keyword_search_only is incompatible with image search. Use it when you need exact keyword matching instead of semantic search.
• Products have rich image metadata including shot_type (hero, lifestyle, on_model, etc.) and photo_quality (professional, ugc, poor) — useful for building polished product displays.