Catalog
Download the complete public OpenAPI schema
Catalog
Buyer-side catalog endpoints to search items and get details for one or more items. This catalog consolidates catalog endpoints across known agentic merchants, both published by OpenMerchant and across the web.
POST /v1/catalog
Search the agentic catalog
Search normalized products and services from published OpenMerchant listings, verified public UCP catalogs, and Shopify Global Catalog. Provider failures are reported through source statuses while healthy results remain available. Unscoped public-UCP search is a bounded live federation, so pagination may report exhaustive=false when lower-ranked merchants were omitted, a merchant failed, or an upstream cursor could not safely continue. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published sources. A valid secret API key or scoped chat actor retains its immutable account and test/live mode. X-Mode and mode query hints cannot override either scope.
Parameters, request, responses, and security
{
"tags": [
"catalog"
],
"summary": "Search the agentic catalog",
"description": "Search normalized products and services from published OpenMerchant listings, verified public UCP catalogs, and Shopify Global Catalog. Provider failures are reported through source statuses while healthy results remain available. Unscoped public-UCP search is a bounded live federation, so pagination may report exhaustive=false when lower-ranked merchants were omitted, a merchant failed, or an upstream cursor could not safely continue. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published sources. A valid secret API key or scoped chat actor retains its immutable account and test/live mode. X-Mode and mode query hints cannot override either scope.",
"operationId": "v1_search_catalog",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1CatalogSearchRequest-Input"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"headers": {
"OpenMerchant-Attribution-Id": {
"description": "Opaque merchant-scoped discovery token that may be echoed into a later MPP order or UCP checkout.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/app__schemas__sourcing__public_catalog_v1__V1CatalogSearchResponse"
}
}
}
},
"429": {
"description": "A shared request rate limit was exceeded.",
"headers": {
"Retry-After": {
"description": "Seconds until this caller may retry.",
"schema": {
"type": "integer",
"minimum": 1.0
}
},
"X-RateLimit-Limit": {
"description": "Request limit for the exhausted window.",
"schema": {
"type": "integer",
"minimum": 1.0
}
},
"X-RateLimit-Window": {
"description": "Length of the exhausted window in seconds.",
"schema": {
"type": "integer",
"minimum": 1.0
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RateLimitExceededResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
},
{}
],
"x-api-audience": "public_v1",
"x-api-authentication": "optional",
"x-operation-id": "v1_search_catalog",
"x-mcp-exposed": true,
"x-public-path": "/v1/catalog",
"x-docs-kind": "create",
"x-docs-order": 10,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/catalog \\\n -H 'Authorization: Bearer pr_sk_test_...'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_search_catalog\",\n \"arguments\": {}\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_search_catalog\",\n arguments: {},\n});"
}
]
}
POST /v1/catalog/impressions
Confirm rendered catalog cards
Idempotently confirm one to six catalog cards after a platform has durably committed their presentation. Each line must carry the high-entropy attribution ID returned with the catalog response and the exact response-facing item and optional variant identifiers. Each item and exact variant can increment confirmed analytics only once for its originating catalog response, even across distinct presentation IDs. Attribution IDs expire at the request-context retention deadline (90 days by default).
Parameters, request, responses, and security
{
"tags": [
"catalog"
],
"summary": "Confirm rendered catalog cards",
"description": "Idempotently confirm one to six catalog cards after a platform has durably committed their presentation. Each line must carry the high-entropy attribution ID returned with the catalog response and the exact response-facing item and optional variant identifiers. Each item and exact variant can increment confirmed analytics only once for its originating catalog response, even across distinct presentation IDs. Attribution IDs expire at the request-context retention deadline (90 days by default).",
"operationId": "v1_confirm_catalog_impressions",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfirmedImpressionsCreate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfirmedImpressionsRead"
}
}
}
},
"429": {
"description": "A shared request rate limit was exceeded.",
"headers": {
"Retry-After": {
"description": "Seconds until this caller may retry.",
"schema": {
"type": "integer",
"minimum": 1.0
}
},
"X-RateLimit-Limit": {
"description": "Request limit for the exhausted window.",
"schema": {
"type": "integer",
"minimum": 1.0
}
},
"X-RateLimit-Window": {
"description": "Length of the exhausted window in seconds.",
"schema": {
"type": "integer",
"minimum": 1.0
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RateLimitExceededResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [],
"x-api-audience": "public_v1",
"x-api-authentication": "none",
"x-operation-id": "v1_confirm_catalog_impressions",
"x-mcp-exposed": false,
"x-public-path": "/v1/catalog/impressions",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 1000
}
POST /v1/catalog/lookup
Look up catalog products
Resolve one to ten product, variant, SKU, handle, or URL identifiers under one exact merchant id, slug, or domain. Partial matches return 200 with typed correlations and missing_ids. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published sources. A valid secret API key or scoped chat actor retains its immutable account and test/live mode. X-Mode and mode query hints cannot override either scope.
Parameters, request, responses, and security
{
"tags": [
"catalog"
],
"summary": "Look up catalog products",
"description": "Resolve one to ten product, variant, SKU, handle, or URL identifiers under one exact merchant id, slug, or domain. Partial matches return 200 with typed correlations and missing_ids. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published sources. A valid secret API key or scoped chat actor retains its immutable account and test/live mode. X-Mode and mode query hints cannot override either scope.",
"operationId": "v1_lookup_catalog_products",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1CatalogLookupRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1CatalogLookupResponse"
}
}
}
},
"429": {
"description": "A shared request rate limit was exceeded.",
"headers": {
"Retry-After": {
"description": "Seconds until this caller may retry.",
"schema": {
"type": "integer",
"minimum": 1.0
}
},
"X-RateLimit-Limit": {
"description": "Request limit for the exhausted window.",
"schema": {
"type": "integer",
"minimum": 1.0
}
},
"X-RateLimit-Window": {
"description": "Length of the exhausted window in seconds.",
"schema": {
"type": "integer",
"minimum": 1.0
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RateLimitExceededResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
},
{}
],
"x-api-audience": "public_v1",
"x-api-authentication": "optional",
"x-operation-id": "v1_lookup_catalog_products",
"x-mcp-exposed": true,
"x-public-path": "/v1/catalog/lookup",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/catalog/lookup \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"ids\": [\n \"...\"\n ],\n \"merchant\": {}\n}'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_lookup_catalog_products\",\n \"arguments\": {\n \"ids\": [\n \"...\"\n ],\n \"merchant\": {}\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_lookup_catalog_products\",\n arguments: {\n \"ids\": [\n \"...\"\n ],\n \"merchant\": {}\n},\n});"
}
]
}
POST /v1/catalog/product
Get a catalog product
Retrieve one complete normalized product under an exact merchant id, slug, or domain using a product, variant, SKU, handle, or URL identifier. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published sources. A valid secret API key or scoped chat actor retains its immutable account and test/live mode. X-Mode and mode query hints cannot override either scope.
Parameters, request, responses, and security
{
"tags": [
"catalog"
],
"summary": "Get a catalog product",
"description": "Retrieve one complete normalized product under an exact merchant id, slug, or domain using a product, variant, SKU, handle, or URL identifier. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published sources. A valid secret API key or scoped chat actor retains its immutable account and test/live mode. X-Mode and mode query hints cannot override either scope.",
"operationId": "v1_get_catalog_product",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1CatalogProductRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1CatalogProductResponse"
}
}
}
},
"429": {
"description": "A shared request rate limit was exceeded.",
"headers": {
"Retry-After": {
"description": "Seconds until this caller may retry.",
"schema": {
"type": "integer",
"minimum": 1.0
}
},
"X-RateLimit-Limit": {
"description": "Request limit for the exhausted window.",
"schema": {
"type": "integer",
"minimum": 1.0
}
},
"X-RateLimit-Window": {
"description": "Length of the exhausted window in seconds.",
"schema": {
"type": "integer",
"minimum": 1.0
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RateLimitExceededResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
},
{}
],
"x-api-audience": "public_v1",
"x-api-authentication": "optional",
"x-operation-id": "v1_get_catalog_product",
"x-mcp-exposed": true,
"x-public-path": "/v1/catalog/product",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/catalog/product \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"id\": \"om_agci_4c1a\",\n \"merchant\": {}\n}'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_get_catalog_product\",\n \"arguments\": {\n \"id\": \"om_agci_4c1a\",\n \"merchant\": {}\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_get_catalog_product\",\n arguments: {\n \"id\": \"om_agci_4c1a\",\n \"merchant\": {}\n},\n});"
}
]
}