POST /products/lookup — resolve a product URL

POST /v1/products/lookup resolves one product page URL and returns a source-aware MerchantProductUrlLookupResponse. The default auto mode checks Octogen’s product index first, then uses on-demand product resolution if the URL is not indexed and that capability is available.

Request

POST https://api.octogen.ai/v1/products/lookup
Authorization: Bearer <your-platform-api-key>
Content-Type: application/json

Body parameters

string

required

Product page URL to resolve. The URL does not need to belong to an Octogen catalog unless resolutionMode is index_only.

string

default:"auto"

Source selection policy. auto checks the index and then resolves on demand after a miss. index_only never performs outbound work. on_demand_only skips the index. Allowed values: auto, index_only, on_demand_only.

string

default:"prefer_cache"

Cache behavior when the request can enter the on-demand path. prefer_cache reuses a recent result when available. refresh requests a fresh resolution but does not bypass safety checks or rate limits. Allowed values: prefer_cache, refresh. This field does not apply to index_only.

Example

curl -sS https://api.octogen.ai/v1/products/lookup \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products/blue-linen-dress",
    "resolutionMode": "auto",
    "onDemandCachePolicy": "prefer_cache"
  }'

Response

string | null

Request identifier for tracing an on-demand resolution. It may be null for an indexed hit.

"indexed" | "on_demand"

required

Source that produced the successful result.

string | null

Catalog key for an indexed result. null for an on-demand result.

string | null

Human-readable catalog name for an indexed result. null for an on-demand result.

string | null

Catalog source base URL for an indexed result. null for an on-demand result or when not configured.

MerchantProductView

required

Product detail view. productUrl is always present. For on-demand results, uuid, catalogKey, and isActive are null; unsupported fields are null, omitted, or empty according to their existing schema defaults.

Show Identity and core fields

string | null

required

Stable indexed identifier. null for an on-demand result.

string | null

Supplying catalog for an indexed product. null for an on-demand result.

string

required

Product page URL.

string | null

Product display name.

BrandView | null

Brand information when available.

number | null

Current selling price.

number | null

Pre-discount price.

string | null

Currency code when available. This is especially important for results without catalog currency context.

string | null

Primary product image URL.

string[]

Product image URLs.

boolean | null

Indexed lifecycle state. null for an on-demand result.

datetime | null

Last indexed update timestamp when available.

Show Extended fields

string | null

Product description.

boolean | null

Current stock evidence.

CategoryView[]

Product categories.

string[]

Available size labels.

ColorView[]

Available colors.

string[]

Product tags.

MerchantVariantView[]

SKU-level variants.

ProductDetailsView

Materials, fit, dimensions, and patterns.

AudienceView | null

Gender and age-group data.

IdentifiersView

Merchant and global identifiers.

BreadcrumbView[]

Merchant navigation path.

PromotionView[]

Active promotions.

ReviewView[]

Customer reviews.

VideoView[]

Product videos.

ProductEnrichment | null

Octogen enrichment for indexed products when available.

string | null

The URL you submitted, echoed back on every successful result.

string | null

Final URL after redirects. Populated for on-demand results when available; use it for on-demand follow-up lookups.

string | null

The matched product’s URL as normalized by Octogen (HTTPS-forced, www. stripped, tracking parameters removed, query sorted). Populated for indexed results. This is the stable URL: submit it on a follow-up lookup and it deterministically re-resolves the same product. Prefer storing it over the URL you originally submitted.

string | null

The canonical URL the product page itself declares (JSON-LD url, og:url, or link rel="canonical"). Populated only for on-demand results; when the page declares none, the resolver currently falls back to the final fetched URL, so a non-null value is not proof of a declaration. null for indexed results. For follow-up lookups use normalizedUrl (indexed) or resolvedUrl (on-demand), not this field.

ProductResolutionMetadata | null

On-demand resolution metadata. null for indexed results.

Show ProductResolutionMetadata properties

"complete" | "partial"

required

Whether all expected shallow product fields were available.

"json_ld" | "open_graph" | "html_meta" | "resolved_url"

required

Strongest page evidence used for the result.

boolean

false for the current direct-HTML path.

string[]

Expected fields that were not available.

"hit" | "miss" | "refresh" | null

Cache outcome for an on-demand result. null for an indexed result.

string[]

Non-fatal warnings about the result.

Indexed example

{
  "source": "indexed",
  "catalogKey": "warrenlotas",
  "catalogDisplayName": "Warren Lotas",
  "sourceBaseUrl": "https://warrenlotas.com",
  "requestedUrl": "https://warrenlotas.com/products/black-hoodie",
  "normalizedUrl": "https://warrenlotas.com/products/black-hoodie",
  "canonicalUrl": null,
  "product": {
    "uuid": "prod_01HX...",
    "catalogKey": "warrenlotas",
    "productUrl": "https://warrenlotas.com/products/black-hoodie",
    "title": "Black Hoodie",
    "currentPrice": 180,
    "currency": "USD",
    "isActive": true
  },
  "resolution": null,
  "cacheStatus": null,
  "warnings": []
}

On-demand example

{
  "requestId": "req_01J...",
  "source": "on_demand",
  "catalogKey": null,
  "catalogDisplayName": null,
  "sourceBaseUrl": null,
  "product": {
    "uuid": null,
    "catalogKey": null,
    "productUrl": "https://example.com/products/blue-linen-dress",
    "title": "Blue Linen Dress",
    "currentPrice": 128,
    "currency": "USD",
    "isActive": null
  },
  "requestedUrl": "https://example.com/products/blue-linen-dress",
  "resolvedUrl": "https://example.com/products/blue-linen-dress",
  "normalizedUrl": null,
  "canonicalUrl": "https://example.com/products/blue-linen-dress",
  "resolution": {
    "completeness": "partial",
    "method": "json_ld",
    "rendered": false,
    "missingFields": ["inStock"]
  },
  "cacheStatus": "miss",
  "warnings": []
}

Errors

Status	`detail`	Meaning
`404`	`product_not_found`	The selected sources did not return a useful product.
`422`	`invalid_product_url`	The URL is malformed or unsupported.
`422`	`unsafe_url`	The URL failed outbound safety checks.
`429`	`rate_limit_exceeded` or `product_lookup_rate_limited`	A service-wide lookup budget is exhausted. Honor `Retry-After`.
`502`	`product_lookup_upstream_failed`	The merchant page failed upstream.
`503`	`product_lookup_fallback_unavailable`	On-demand resolution is temporarily unavailable.
`504`	`product_lookup_timed_out`	The bounded lookup deadline expired.

See Error Handling and Rate Limits.

SDK equivalents

result = await client.lookup_product(
    "https://example.com/products/blue-linen-dress",
    resolution_mode="auto",
    on_demand_cache_policy="prefer_cache",
)

if result.source == "indexed":
    print(result.catalog_key, result.product.uuid)
else:
    print(result.product.title, result.resolution)

const result = await client.lookupProduct(
  "https://example.com/products/blue-linen-dress",
  { resolutionMode: "auto", onDemandCachePolicy: "prefer_cache" }
);

if (result.source === "indexed") {
  console.log(result.catalogKey, result.product.uuid);
} else {
  console.log(result.product.title, result.resolution);
}

On-demand results are ephemeral and do not create an indexed product UUID. If your integration requires indexed identity and catalog context, set resolutionMode to index_only.

Catalog API

Voyage API

Coverage API

Data Models

POST /products/lookup — resolve a product URL

Request

Body parameters

Example

Response

Indexed example

On-demand example

Errors

SDK equivalents

​Request

​Body parameters

​Example

​Response

​Indexed example

​On-demand example

​Errors

​SDK equivalents

Request

Body parameters

Example

Response

Indexed example

On-demand example

Errors

SDK equivalents