Catalog - REST Binding

This document specifies the HTTP/REST binding for the Catalog Capability.

Protocol Fundamentals

Discovery

Businesses advertise REST transport availability through their UCP profile at /.well-known/ucp.

{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "rest": {
          "schema": "https://ucp.dev/2026-01-11/services/shopping/rest.openapi.json",
          "endpoint": "https://business.example.com/ucp"
        }
      }
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{
        "version": "2026-01-11",
        "spec": "https://ucp.dev/2026-01-11/specification/catalog/search",
        "schema": "https://ucp.dev/2026-01-11/schemas/shopping/catalog_search.json"
      }],
      "dev.ucp.shopping.catalog.lookup": [{
        "version": "2026-01-11",
        "spec": "https://ucp.dev/2026-01-11/specification/catalog/lookup",
        "schema": "https://ucp.dev/2026-01-11/schemas/shopping/catalog_lookup.json"
      }]
    }
  }
}

Endpoints

Endpoint	Method	Capability	Description
`/catalog/search`	POST	Search	Search for products.
`/catalog/lookup`	POST	Lookup	Lookup one or more products by ID.

`POST /catalog/search`

Maps to the Catalog Search capability.

Example

=== “Request”

```json
POST /catalog/search HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Content-Type: application/json

{
  "query": "blue running shoes",
  "context": {
    "address_country": "US",
    "address_region": "CA",
    "intent": "looking for comfortable everyday shoes"
  },
  "filters": {
    "categories": ["Footwear"],
    "price": {
      "max": 15000
    }
  },
  "pagination": {
    "limit": 20
  }
}
```

=== “Response”

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [{"version": "2026-01-11"}]
    }
  },
  "products": [
    {
      "id": "prod_abc123",
      "handle": "blue-runner-pro",
      "title": "Blue Runner Pro",
      "description": {
        "plain": "Lightweight running shoes with responsive cushioning."
      },
      "url": "https://business.example.com/products/blue-runner-pro",
      "categories": [
        { "value": "187", "taxonomy": "google_product_category" },
        { "value": "Footwear > Running", "taxonomy": "merchant" }
      ],
      "price_range": {
        "min": { "amount": 12000, "currency": "USD" },
        "max": { "amount": 12000, "currency": "USD" }
      },
      "media": [
        {
          "type": "image",
          "url": "https://cdn.example.com/products/blue-runner-pro.jpg",
          "alt_text": "Blue Runner Pro running shoes"
        }
      ],
      "options": [
        {
          "name": "Size",
          "values": [{"label": "8"}, {"label": "9"}, {"label": "10"}]
        }
      ],
      "variants": [
        {
          "id": "prod_abc123_size10",
          "sku": "BRP-BLU-10",
          "title": "Size 10",
          "price": { "amount": 12000, "currency": "USD" },
          "availability": { "available": true },
          "selected_options": [{"name": "Size", "label": "10"}],
          "tags": ["running", "road", "neutral"]
        }
      ],
      "rating": {
        "value": 4.5,
        "scale_max": 5,
        "count": 128
      }
    }
  ],
  "pagination": {
    "cursor": "eyJwYWdlIjoxfQ==",
    "has_next_page": true,
    "total_count": 47
  }
}
```

`POST /catalog/lookup`

Maps to the Catalog Lookup capability. See capability documentation for supported identifiers, resolution behavior, and client correlation requirements.

Example: Batch Lookup

=== “Request”

```json
POST /catalog/lookup HTTP/1.1
Host: business.example.com
Content-Type: application/json

{
  "ids": ["prod_abc123", "prod_def456"],
  "context": {
    "address_country": "US"
  }
}
```

=== “Response”

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": {
      "dev.ucp.shopping.catalog.lookup": [{"version": "2026-01-11"}]
    }
  },
  "products": [
    {
      "id": "prod_abc123",
      "title": "Blue Runner Pro",
      "variants": [
        {
          "id": "prod_abc123_size10",
          "title": "Size 10",
          "price": { "amount": 12000, "currency": "USD" },
          "availability": { "available": true },
          "inputs": [
            { "id": "prod_abc123", "match": "featured" }
          ]
        }
      ]
    }
  ]
}
```

Example: Partial Success (Some Identifiers Not Found)

=== “Request”

```json
{
  "ids": ["prod_abc123", "prod_invalid", "prod_def456"]
}
```

=== “Response”

```json
{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": {
      "dev.ucp.shopping.catalog.lookup": [{"version": "2026-01-11"}]
    }
  },
  "products": [
    {
      "id": "prod_abc123",
      "title": "Blue Runner Pro"
    },
    {
      "id": "prod_def456",
      "title": "Trail Blazer X"
    }
  ],
  "messages": [
    {
      "type": "info",
      "code": "not_found",
      "content": "prod_invalid"
    }
  ]
}
```

Error Handling

UCP uses a two-layer error model separating transport errors from business outcomes.

Transport Errors

Use HTTP status codes for protocol-level issues that prevent request processing:

Status	Meaning
400	Bad Request - Malformed JSON or missing required parameters
401	Unauthorized - Missing or invalid authentication
429	Too Many Requests - Rate limited
500	Internal Server Error

Business Outcomes

All application-level outcomes return HTTP 200 with the UCP envelope and optional messages array. See Catalog Overview for message semantics and common scenarios.

Conformance

A conforming REST transport implementation MUST:

Implement endpoints for each catalog capability advertised in the business’s UCP profile.
Return products with valid Price objects (amount + currency).
Support cursor-based pagination with default limit of 10.
Return HTTP 200 for lookup requests; unknown identifiers result in fewer products returned.
Return HTTP 400 with request_too_large error for requests exceeding batch size limits.