Registry
Download the complete public OpenAPI schema
Registry
Aggregate directory for merchants with agentic commerce protocols enabled across the Internet, including known MPP and UCP enabled merchants. Use these endpoints for buyer-side convenience without scraping or aggregating yourself
GET /v1/registry
Search combined agentic registry
Search for merchants that have agentic commerce protocols enabled and filter by category, payment method, or protocol. This endpoint combines our internal registry, MPP registry, and merchants with known UCP profiles. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published merchants. A valid secret API key or scoped chat actor retains its immutable account and test/live mode, including owner previews. X-Mode and mode query hints cannot override either scope.
Parameters, request, responses, and security
{
"tags": [
"registry"
],
"summary": "Search combined agentic registry",
"description": "Search for merchants that have agentic commerce protocols enabled and filter by category, payment method, or protocol. This endpoint combines our internal registry, MPP registry, and merchants with known UCP profiles. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published merchants. A valid secret API key or scoped chat actor retains its immutable account and test/live mode, including owner previews. X-Mode and mode query hints cannot override either scope.",
"operationId": "v1_list_registry",
"parameters": [
{
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"maxLength": 255,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Q"
},
"name": "q",
"in": "query"
},
{
"required": false,
"schema": {
"$ref": "#/components/schemas/RegistryProtocolFilter",
"default": "all"
},
"name": "protocol",
"in": "query"
},
{
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/AgenticCatalogItemType"
},
{
"type": "null"
}
],
"title": "Commerce Category"
},
"name": "commerce_category",
"in": "query"
},
{
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"maxLength": 100,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Mpp Category"
},
"name": "mpp_category",
"in": "query"
},
{
"description": "Normalized buyer-facing payment methods. Generic card handlers use card; provider-specific choices retain their own values. Repeated values use OR semantics.",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/RegistryPaymentMethodFilter"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Payment Method",
"description": "Normalized buyer-facing payment methods. Generic card handlers use card; provider-specific choices retain their own values. Repeated values use OR semantics."
},
"name": "payment_method",
"in": "query"
},
{
"description": "Granular instruments advertised beneath the selected payment handler, matched with OR semantics.",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/RegistryPaymentInstrument"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Payment Instrument",
"description": "Granular instruments advertised beneath the selected payment handler, matched with OR semantics."
},
"name": "payment_instrument",
"in": "query"
},
{
"required": false,
"schema": {
"type": "integer",
"maximum": 100.0,
"minimum": 1.0,
"title": "Limit",
"default": 8
},
"name": "limit",
"in": "query"
},
{
"required": false,
"schema": {
"type": "integer",
"maximum": 10000.0,
"minimum": 0.0,
"title": "Offset",
"default": 0
},
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegistryListResponse"
}
}
}
},
"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_list_registry",
"x-mcp-exposed": true,
"x-public-path": "/v1/registry",
"x-docs-kind": "list",
"x-docs-order": 25,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X GET https://api.openmerchant.dev/v1/registry \\\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_list_registry\",\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_list_registry\",\n arguments: {},\n});"
}
]
}
GET /v1/registry/{entry_id}
Get registry entry
Retrieve protocol endpoints, payment provenance, and representative catalog items for one visible merchant. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published merchants. A valid secret API key or scoped chat actor retains its immutable account and test/live mode, including owner previews. X-Mode and mode query hints cannot override either scope.
Parameters, request, responses, and security
{
"tags": [
"registry"
],
"summary": "Get registry entry",
"description": "Retrieve protocol endpoints, payment provenance, and representative catalog items for one visible merchant. Authentication is deployment-configurable and optional by default. When anonymous access is enabled, anonymous requests always use live mode and see only globally published merchants. A valid secret API key or scoped chat actor retains its immutable account and test/live mode, including owner previews. X-Mode and mode query hints cannot override either scope.",
"operationId": "v1_get_registry_entry",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Entry Id"
},
"name": "entry_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegistryDetailResponse"
}
}
}
},
"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_registry_entry",
"x-mcp-exposed": true,
"x-public-path": "/v1/registry/{entry_id}",
"x-docs-kind": "retrieve",
"x-docs-order": 30,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X GET https://api.openmerchant.dev/v1/registry/... \\\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_get_registry_entry\",\n \"arguments\": {\n \"entry_id\": \"...\"\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_registry_entry\",\n arguments: {\n \"entry_id\": \"...\"\n},\n});"
}
]
}