Your catalog.
A better way to find it.

01 · From sign-up to your first search

1. Open your workspace. Visit api.codehence.com and select Create account.
2. Create a business account. Enter your business email and a password of 12–128 characters. Shoppers do not need an account.
3. Connect your storefront. Enter your store name, currency and website origin, such as https://shop.yourbrand.com. You do not need an admin key.
4. Save your private credentials. Open Integration → Private server integration credentials and securely save the Write key. The public Search key is included in the installation snippet.
5. Import your products. In Catalog, download the CSV template, add your actual products and upload the CSV/JSON file. Review it and select Import / update products.
6. Check relevance. Open Search preview, search for products in your catalog and inspect the results. The preview defaults to in-stock products.
7. Install on your website. In Integration, choose an accent color and select Copy installation code. Add it to your storefront.
8. Validate your storefront. Search from your actual website, verify product links and check mobile layout. Add additional origins under Store settings if required.

Returning customers can sign in and select a store from Current store. Use + Add store to connect another storefront.

02 · Accounts & stores

A merchant account belongs to the store owner or developer managing the catalog. Shoppers do not need a Codehence account to search a storefront.

After signing in, create stores and select them from Current store. Stores belong to the account that created or claimed them. Catalog writes are authorized through your session; you do not have to paste a private key on every visit.

Link a store created before accounts existed

1. Sign in to your merchant account.
2. Select + Add store, then expand Already have a store and API keys?.
3. Enter the existing Store ID, Search key and Write key.
4. Select Link existing store.

Both keys must match. A store already linked to another account cannot be claimed.

03 · Prepare your product catalog

Use a stable ID for each product or sellable variant. Reimporting an existing ID updates it. A missing row in a new import does not delete an existing product; use Catalog → Remove a product or the delete API for removal.

JSON example

{
  "products": [{
    "id": "shoe-001-size9",
    "title": "Everyday Running Shoes",
    "description": "Lightweight sneakers for daily runs",
    "price": 89,
    "currency": "USD",
    "category": "Shoes",
    "inStock": true,
    "attributes": { "color": "black", "size": "9" },
    "url": "https://shop.example.com/products/shoe-001"
  }]
}

CSV example

id,title,price,currency,inStock,attributes.color
shoe-001,Everyday Running Shoes,89,USD,true,black
bag-001,"Waterproof Bag, 22L",79,USD,true,green

CSV headers are case-sensitive. Required headers: id,title,price. Use attributes.color, attributes.size and similar headers for attributes. Quote fields containing commas or line breaks; escape a literal quote as "". Uploading a file previews it in the editor. Select Import / update to save.

Limits: up to 1,000 products per import and 2 MB per request. Split larger catalogs into batches. A validation failure rejects the full import batch. JSON uploads accept either a product array or an object containing products.

04 · Search & filters

Without AI configuration, Codehence uses keyword matching, a small synonym map and query rules. Recognized phrases include under $100, above $50, between $50 and $150, common English colors and in stock.

{
  "query": "black running shoes under $100",
  "filters": { "inStock": true },
  "page": 1,
  "pageSize": 12
}

Explicit filters override filters interpreted from the query. Supported fields are priceMin, priceMax, color, category and inStock. Page size is 1–100. Color and category filters compare complete values without case sensitivity. Arbitrary attribute filters and size interpretation are not implemented.

Response fields include products, total, page, pageSize, interpretedFilters, facets.categories, engine and semanticSearch. lexical-rules-v1 means keyword/rule-based retrieval; hybrid-rrf-v1 means hybrid retrieval was used. A blank query browses products with explicit filters.

05 · Add search to your website

Open Integration in your workspace to generate a snippet containing your Store ID and public Search key. Choose an accent color and copy the code to your storefront. The example below uses the production service domain; replace the Store ID and public Search key. This is the browser widget API; there is no published npm SDK package.

<div id="codehence-search"></div>
<script src="https://api.codehence.com/widget.js"></script>
<script>
  const widget = Codehence.mount('#codehence-search', {
    endpoint: 'https://api.codehence.com',
    storeId: 'YOUR_STORE_ID',
    searchKey: 'YOUR_PUBLIC_SEARCH_KEY',
    accent: '#cefa89'
  });
  // When removing the component: widget.destroy();
</script>

1. In Store settings → Allowed website origins, allow the exact storefront origin: scheme, hostname and port if applicable. Use no path or trailing slash. www and non-www hosts are different origins.
2. Place the snippet in a storefront template or HTML block that permits JavaScript. The target element must exist before mounting.
3. Use the Search key only. Never embed the Write key, admin key or AI-provider key.
4. Test from the real allowed domain.

The installation snippet always uses the configured public service endpoint, even when the workspace is previewed on a development machine. The widget uses Shadow DOM for style isolation. Current customization includes the accent color, mount location, endpoint and store. For a fully custom layout, render results yourself with the REST API. The widget links to product pages when url is provided.

Custom frontend: REST example

const response = await fetch(
  'https://api.codehence.com/v1/stores/YOUR_STORE_ID/search',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer YOUR_PUBLIC_SEARCH_KEY'
    },
    body: JSON.stringify({
      query: 'running shoes under $100',
      filters: { inStock: true },
      pageSize: 12
    })
  }
);
const data = await response.json();
if (!response.ok) throw new Error(data.error);
// Render data.products using safe text/DOM APIs.

If your website uses Content Security Policy, allow the backend under script-src and connect-src. Move inline initialization into your own allowed JavaScript file when inline scripts are prohibited. Shopify, WooCommerce and other platform-specific plugins are not yet shipped; use custom theme/template integration where supported.

06 · API reference

Use Authorization: Bearer YOUR_KEY and JSON request bodies. Browser dashboard sessions can authorize owned-store operations; external server integrations use API keys.

Server-side catalog updates

// Run on your server. Load the private key from environment secrets.
const response = await fetch(
  `${process.env.CODEHENCE_ENDPOINT}/v1/stores/${process.env.CODEHENCE_STORE_ID}/products`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.CODEHENCE_WRITE_KEY}`
    },
    body: JSON.stringify({ products: updatedProducts })
  }
);
const result = await response.json();
if (!response.ok) throw new Error(result.error);

Catalog changes currently require imports or explicit API calls; automatic platform synchronization/webhooks are not configured. Default request limits are 120 requests per minute per store for search and a separate write bucket. Handle 429 by waiting for the Retry-After duration.

07 · Enable semantic search

Semantic search is managed by the Codehence operator. Store owners do not need to create an AI-provider account or enter a provider key in the dashboard. Keyword search remains available when semantic search is not enabled.

1. Open Search preview → Search index status to check availability.
2. If semantic search is enabled, select Update semantic index. Repeat until pending products reach zero.
3. Search using descriptive customer intent and compare the results. The displayed mode changes to Hybrid search when a current index is used.
4. If activation is unavailable, contact your Codehence operator; this is server configuration, not a merchant key setting.

Indexing sends product titles, descriptions, category, brand and attributes to the embedding provider. Search sends query text. The platform operator configures and pays the embedding provider. Codehence commercial terms must be agreed separately; billing is not connected in the current release.

Changes to descriptive content require reindexing. Price and stock updates reuse existing embeddings. Products without current embeddings remain eligible for keyword retrieval. Provider failures fall back to lexical search with fallbackReason. The hybrid result set uses up to 100 candidates from each retrieval path; totals/facets describe that candidate set rather than an exhaustive inventory count.

Live semantic relevance, latency and cost still need evaluation on your catalog. See the official OpenAI embeddings API reference for the provider API used by the adapter.

08 · Understand your keys

Store credentials are shown at creation. Signed-in merchants use their session to manage owned stores and can copy the public Search key from Integration. Private Write keys are not recoverable through the dashboard; save them securely when first issued.

Allowed origins are a browser CORS boundary, not a way to make a public Search key secret. Cookie sessions are HttpOnly and SameSite=Strict, with Secure enabled in production. HTTPS is required for hosted merchant sessions.

09 · Troubleshooting

10 · Before enabling search for shoppers

• Confirm your store currency, product prices, availability and product URLs are correct.
• Allow all real storefront origins in Store settings, including www/non-www where applicable.
• Keep private Write keys in server secrets; use only the public Search key in storefront code.
• Check exact product names, descriptive searches, price constraints and empty results.
• Test the installed widget on your real domain, desktop and mobile. Ensure your CSP permits the service’s scripts and requests.
• Use the catalog API or repeat imports to keep stock and prices current.