Skip to main content
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

​
url
string
required
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.
​
catalogKey
string
required
The catalog key the product was found in. Matches the catalog field on a MerchantCatalogSummary.
​
catalogDisplayName
string
required
Human-readable name of the catalog containing this product.
​
sourceBaseUrl
string | null
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.

​
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

StatusdetailMeaning
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())

import { OctogenClient, OctogenNotFoundError } from "@octogen-ai/sdk";

const client = new OctogenClient();
try {
  const result = await client.lookupProduct(
    "https://warrenlotas.com/products/black-hoodie"
  );
  console.log(result.catalogKey, result.product.title, result.product.currentPrice);
} catch (error) {
  if (error instanceof OctogenNotFoundError) {
    console.log("Product not found in any granted catalog.");
  } else {
    throw error;
  }
}