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.
POST /products/lookup takes a product page URL and returns the full canonical product record for that URL from within your granted catalogs. The response includes catalog metadata alongside a MerchantProductView — the richest product shape the API offers, with optional fields like variants, colors, reviews, breadcrumbs, and enrichment populated whenever the underlying record has them.Request POST https://api.octogen.ai/v1/products/lookup Authorization : Bearer <your-platform-api-key> Content-Type : application/json
Body parameters The canonical product page URL to resolve. Must be a URL belonging to a catalog granted to your organization.
Example curl -sS https://api.octogen.ai/v1/products/lookup \ -H "Authorization: Bearer $OCTOGEN_PLATFORM_API_KEY " \ -H "Content-Type: application/json" \ -d '{"url": "https://warrenlotas.com/products/black-hoodie"}'
Response The response is a MerchantProductUrlLookupResponse object.
The catalog key the product was found in. Matches the catalog field on a MerchantCatalogSummary.
Human-readable name of the catalog containing this product.
Base URL of the merchant’s product site. May be null if not configured on the catalog.
product
MerchantProductView
required
Full product record. Extends the search list item shape with additional detail fields. Show Core fields (shared with search results)
Stable unique identifier for this product record.
Canonical product page URL.
Product title as indexed from the merchant.
Brand information. Show BrandView properties
URL-safe brand identifier.
URL of the brand’s page on the merchant site.
Current sale or listing price.
Pre-discount price. null when no discount is present.
Primary product image URL.
All product image URLs including the primary image.
Aggregate customer rating. Show RatingView properties
ISO 8601 UTC timestamp of the last update to this product record.
Show Extended fields (lookup only)
Full product description.
Whether any variant is currently in stock.
Categories assigned to the product. Each item has name (string) and optional url (string).
Available size labels, e.g. ["s", "m", "l", "xl"].
Available colors. Each item has label (string), optional hexCode (string), and optional swatchUrl (string).
Free-form tags associated with the product.
Individual SKU-level variants. Each variant has sku, productUrl, color, size, inStock, and imageUrl.
Structured product attributes: materials (string[]), fit (string[]), dimensions (string | null), patterns (string[]).
Intended audience. Has genders (string[]) and ageGroups (string[]).
External product identifiers. Show IdentifiersView properties
Merchant’s internal product ID.
Global Trade Item Number (barcode).
ID grouping product variants together.
Navigation path on the merchant site. Each item has name (string) and optional url (string).
Active promotions. Each item has optional description (string) and code (string).
Customer reviews. Each item has optional author, rating, body, and publishedAt fields.
Associated product videos. Each item has optional url, thumbnailUrl, and name fields.
Octogen-generated enrichment data including type, gender, age_groups, color, color_family, category_path, attributes, and canonical_brand.
Example response { "catalogKey" : "warrenlotas" , "catalogDisplayName" : "Warren Lotas" , "sourceBaseUrl" : "https://warrenlotas.com" , "product" : { "uuid" : "prod_01HX..." , "title" : "Black Hoodie" , "description" : "Heavyweight cotton hoodie with screen-printed graphics." , "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" , "swatchUrl" : null }], "tags" : [ "hoodie" , "black" ], "identifiers" : { "productId" : "WL-BH-001" , "gtin" : null , "productGroupId" : null }, "updatedAt" : "2026-05-19T18:04:10Z" } }
Errors Status detailMeaning 404"product_not_found"No product matching the URL was found in any catalog granted to your key.
A 404 means the URL is either not indexed in any of your granted catalogs or
does not belong to a catalog your organization has access to. Confirm the URL
is a valid product page for a granted catalog and that the catalog key is
active via GET /catalogs.
SDK equivalents import asyncio from octogen_ai_sdk import OctogenClient, OctogenNotFoundError async def main () -> None : async with OctogenClient() as client: try : result = await client.lookup_product( "https://warrenlotas.com/products/black-hoodie" ) print (result.catalog_key, result.product.title, result.product.current_price) except OctogenNotFoundError: print ( "Product not found in any granted catalog." ) asyncio.run(main())
