> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychannel3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lookup Catalog

**`lookup_catalog`** turns ids or URLs into full product records.

* **`catalog.ids`** - Channel3 product ids (or variant ids)
* **`catalog.urls`** - links to a product page on a store's website

Don't put `https://...` links in `ids`. Use `urls` for those.

Examples below use **UCP CLI** and **curl**. See [quickstart](/ucp/quickstart.md) to install the CLI.

## By product ID

```bash UCP CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
ucp catalog lookup \
  --input '{"ids":["HvGOfxD","cp_def456"]}' \
  --format json
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST https://ucp.trychannel3.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "lookup_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "ids": ["HvGOfxD", "cp_def456"]
        }
      }
    }
  }'
```

You get one product per ID when we have it. Missing ids show up in `messages` but won't fail the whole request.

## By product URL

```bash UCP CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
ucp catalog lookup \
  --input '{"urls":["https://merchant.example.com/products/some-shoe"]}' \
  --format json
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST https://ucp.trychannel3.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "lookup_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "urls": [
            "https://merchant.example.com/products/some-shoe"
          ]
        }
      }
    }
  }'
```

We match the URL to our index and return the product with **every store's offer as a separate entry in `variants[]`** (same as `POST /v1/lookup`). Multiple sellers for one product means multiple variants — see [Extension reference](/ucp/catalog-global-extension.md#variants-per-store-listings).

For interactive variant selection (`selected`, `preferences`), use [`get_product`](/ucp/get-product) instead.

> [!WARNING]
>
> If you put a URL in **`catalog.ids`**, you'll get a message telling you to use
> **`catalog.urls`** instead.

## Both at once

You can send `ids` and `urls` in one request if your agent has a mix.

```bash UCP CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
ucp catalog lookup \
  --input '{"ids":["HvGOfxD"],"urls":["https://merchant.example.com/products/some-shoe"]}' \
  --format json
```

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST https://ucp.trychannel3.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "lookup_catalog",
      "arguments": {
        "meta": null,
        "catalog": {
          "ids": ["HvGOfxD"],
          "urls": ["https://merchant.example.com/products/some-shoe"]
        }
      }
    }
  }'
```

## What's next

> **[Get one product](/ucp/get-product.md)**
>
> When you only need a single ID


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.