Skip to main content

​
Installation

// npm
npm install @channel3/sdk

// yarn
yarn add @channel3/sdk

// pnpm
pnpm add @channel3/sdk

​
Authentication

You can provide your API key using the CHANNEL3_API_KEY environment variable, or by passing it directly to the client. 
import Channel3 from "@channel3/sdk";

// Initialize with environment variable
const client = new Channel3();

// Or, initialize with API key directly
const clientWithKey = new Channel3({
  apiKey: "your_api_key_here",
});

​
Usage

All top-level endpoints are available as properties on the client. For example, to use the search endpoint: 
import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  const response = await client.search.perform({
    query: "organic cotton t-shirt",
  });

  console.log(response);
}

main();

​
Async Usage

import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  const response = await client.search.perform({
    query: "organic cotton t-shirt",
  });
  console.log(response);
}

main();

​
Advanced Usage

​
Search with filters

import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  const response = await client.search.perform({
    query: "running shoes",
    filters: {
      brand_ids: [brand_id1, brand_id2],
      gender: "unisex",
      price: { min_price: 50.0, max_price: 150.0 },
      availability: ["InStock", "LimitedAvailability"],
    },
    limit: 20,
  });
  console.log(response);
}

main();

​
Search with an image URL

import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  const response = await client.search.perform({
    image_url: "https://example.com/images/shoe.jpg",
    limit: 12,
  });
  console.log(response);
}

main();

​
Search with a base64 image

import fs from "node:fs";
import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  const b64 = fs.readFileSync("shoe.jpg").toString("base64");
  const response = await client.search.perform({
    base64_image: b64,
    limit: 12,
  });
  console.log(response);
}

main();

​
Configure search behavior

import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  const response = await client.search.perform({
    query: "linen shirt",
    config: {
      enrich_query: false, // default true
      semantic_search: true, // default true
    },
  });
  console.log(response);
}

main();

​
Provide request context

import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  const response = await client.search.perform({
    query: "sneakers",
    context: "Free text describing the end-user who the search is for.",
    limit: 10,
  });
  console.log(response);
}

main();

​
Enrich a product URL

import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  const response = await client.enrich.perform({
    url: "https://brand.com/products/linen-shirt",
  });
  console.log(response);
}

main();

​
Error Handling

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), an error will be thrown. 
import Channel3 from "@channel3/sdk";

const client = new Channel3();

async function main() {
  try {
    await client.search.perform();
  } catch (err) {
    if (err instanceof Channel3.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  }
}

main();
Error types are exposed via each SDK’s error module.