Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.octogen.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Product lookup resolves a product page URL to the full canonical record Octogen holds for that product. Instead of a lightweight search item, you get the complete product view — description, sizes, colors, variants, identifiers, enrichment metadata, and more. Lookup searches across all catalogs your API key has access to, so you don’t need to know which catalog a URL belongs to before calling it.

​
What lookup does

When you call POST /v1/products/lookup with a product page URL, Octogen matches the URL against active product records across your granted catalogs and returns the canonical record from the first matching catalog. The response tells you which catalog matched (catalogKey, catalogDisplayName) alongside the full product object.
Use caseRecommended endpoint
User pastes or shares a product URLPOST /v1/products/lookup
User types a keyword or browses by categoryPOST /v1/products/search
You want full product detail from a search resultLook up the productUrl from the search item

​
Making a lookup request

Send a POST request to /v1/products/lookup with a JSON body containing the product page URL. 
curl -sS https://api.octogen.ai/v1/products/lookup \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://warrenlotas.com/products/black-hoodie"}'

​
Response fields

The response wraps the catalog context and the full product object.

​
Top-level response

FieldTypeDescription
catalogKeystringThe catalog key that matched the URL (e.g. "warrenlotas").
catalogDisplayNamestringHuman-readable catalog name (e.g. "Warren Lotas").
sourceBaseUrlstring | nullBase domain of the catalog source.
productobjectThe full product record (see below).

​
Product object

The product object extends the search item with additional detail fields:
FieldTypeDescription
uuidstringStable unique identifier for the product.
titlestring | nullProduct display name.
descriptionstring | nullFull product description.
productUrlstringCanonical URL on the retailer’s site.
imageUrlstring | nullPrimary product image URL.
imagesstring[]All product image URLs.
currentPricenumber | nullCurrent selling price.
originalPricenumber | nullPre-discount price, if available.
inStockboolean | nullWhether the product is currently in stock.
sizesstring[]Available sizes (e.g. ["s", "m", "l", "xl"]).
colorsobject[]Available colors, each with label, hexCode, and optional swatchUrl.
tagsstring[]Free-form tags assigned to the product.
identifiersobjectExternal identifiers: productId, gtin, productGroupId.
variantsobject[]Per-variant records with sku, productUrl, color, size, inStock, imageUrl.
categoriesobject[]Category objects with name and optional url.
breadcrumbsobject[]Breadcrumb trail with name and optional url.
audienceobject | nullTarget audience with genders and ageGroups arrays.
detailsobjectStructured product details: materials, fit, dimensions, patterns.
promotionsobject[]Active promotions with optional description and code.
reviewsobject[]Customer reviews with author, rating, body, and publishedAt.
videosobject[]Product videos with url, thumbnailUrl, and name.
enrichmentobject | nullOctogen-computed enrichment: product type, gender, age groups, color family, category path, structured attributes, and canonical brand data.
brandobject | nullBrand with name and optional slug, url, description.
ratingobject | nullAggregate rating with average and count.
updatedAtstring | nullISO 8601 timestamp of the last catalog update.

​
Example response

{
  "catalogKey": "warrenlotas",
  "catalogDisplayName": "Warren Lotas",
  "sourceBaseUrl": "https://warrenlotas.com",
  "product": {
    "uuid": "prod_01HX...",
    "title": "Black Hoodie",
    "description": "Heavyweight cotton hoodie...",
    "productUrl": "https://warrenlotas.com/products/black-hoodie",
    "imageUrl": "https://cdn.example.com/black-hoodie.jpg",
    "images": ["https://cdn.example.com/black-hoodie.jpg"],
    "currentPrice": 180,
    "originalPrice": null,
    "inStock": true,
    "sizes": ["s", "m", "l", "xl"],
    "colors": [{"label": "Black", "hexCode": "#000000"}],
    "tags": ["hoodie", "black"],
    "identifiers": {"productId": "WL-BH-001", "gtin": null, "productGroupId": null},
    "isActive": true,
    "updatedAt": "2026-05-19T18:04:10Z"
  }
}

​
Handling the not-found case

If no active product in your granted catalogs matches the URL, the API returns HTTP 404 with "product_not_found" in the error detail. The SDK raises OctogenNotFoundError. This is not a retryable error — it means the URL is not indexed in any catalog you have access to.
Check that the URL is a canonical product page URL (not a search results page or category page), and that your organization has an active grant for the catalog that sells the product. Use GET /v1/catalogs to confirm your grants.