---
title: "Lookup Product"
method: POST
path: "/v1/lookup"
tags: ["v1"]
---

# Lookup Product

`POST /v1/lookup`

Retrieve product information for any supported product URL.

Returns the same Product model as GET /v1/products/{product_id}.
The product_id in the response can be used with the Product Detail endpoint.

## Request body

- LookupRequest
  - `url` string, required — The URL of the product to look up
  - `max_staleness_hours` integer — Maximum age (in hours) of cached product data before forcing a fresh lookup. Defaults to 3 hours.

## Response `200`

Successful Response

- LookupResponse — Response from the /v1/lookup endpoint.
  - `product` Product, required — Product with detailed information.
    - `id` string, required
    - `title` string, required
    - `description` string, nullable
    - `brands` ProductBrand[] — Ordered list of brands.
      - `id` string, required
      - `name` string, required
    - `images` ProductImage[]
      - `url` string, required
      - `is_main_image` boolean
      - `shot_type` 'hero' | 'lifestyle' | 'on_model' | 'detail' | 'scale_reference' | 'angle_view' | 'flat_lay' | 'in_use' | 'packaging' | 'size_chart' | 'product_information' | 'merchant_information' — Product image type classification for API responses.
      - `alt_text` string, nullable
    - `categories` string[]
    - `gender` 'male' | 'female' | 'unisex', nullable
    - `materials` string[], nullable
    - `key_features` string[], nullable
    - `offers` ProductOffer[] — All merchant offers for this product in the requested locale.
      - `url` string, required
      - `domain` string, required
      - `price` Price, required
        - `price` number, required — The current price of the product, including any discounts.
        - `compare_at_price` number, nullable — The original price of the product before any discounts.
        - `currency` string, required — The currency code of the product, like USD, EUR, GBP, etc.
      - `availability` 'InStock' | 'OutOfStock', required
      - `max_commission_rate` number — The maximum commission rate for the merchant, as a percentage. 0 is no commission. 0.5 is 50% commission. 'Max' because the actual commission rate may be lower due to vendor-specific affiliate rules.

## Other responses

- `401` — Unauthorized - Invalid or missing authentication
- `402` — Payment required
- `404` — Product not found
- `422` — URL is not a product page (e.g. category listing, search results, homepage) or is on an unsupported domain
- `500` — Unable to extract product data from the given URL
- `504` — Timeout

## Changes

- **2026-04-10** `2e3609d564bb` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/channel3-ai/apis/fastapi/changes/v1/lookup/post.md)

---

[API](https://skmtc.dev/channel3-ai/apis/fastapi.md) · [All operations](https://skmtc.dev/channel3-ai/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/channel3-ai/fastapi/revisions/cefefb7bceb2/schema)