R
UCP Registry
API v1

The ecosystem API for UCP commerce

Query verified merchants, agent benchmarks, plugins, and infrastructure across the UCP ecosystem. Build agents that discover stores, or build stores that attract agents.

View endpoints Submit to ecosystem

How it works

Step 1

Agent queries Registry API

An AI agent calls /api/v1/products/search to find products across all stores, or /api/v1/merchants to discover UCP-enabled merchants.

Step 2

Discovers UCP-enabled merchants

The agent receives structured data: domains, platforms, UCP scores, and capability counts for each merchant.

Step 3

Connects via UCP endpoint

The agent connects directly to the merchant UCP endpoint to search products, compare prices, and complete the transaction.

Two tiers of access

Start free for discovery. Authenticate for full data access.

No authentication required. Rate-limited to 30 requests per day, 10 results per page.

  • •Merchant discovery (GET /api/v1/merchants)
  • •Product discovery across all stores (GET /api/v1/products/search)
  • •Filter by query, category, domain, price range, and sort order
GET /api/v1/products/search?q=running+shoes&sort=price_asc&limit=5

{
  "data": [
    {
      "title": "Trail Runner SWT",
      "price": 120.00,
      "currency": "USD",
      "url": "https://allbirds.com/products/trail-runner-swt",
      "image_url": "https://cdn.shopify.com/.../trail-runner.jpg",
      "product_type": "Footwear",
      "merchant": "allbirds.com",
      "store_category": "Apparel & Accessories",
      "platform": "shopify"
    }
  ],
  "meta": {
    "total": 12,
    "returned": 5,
    "merchants": 3,
    "query": "running shoes",
    "sort": "price_asc"
  }
}

Endpoint reference

All endpoints return JSON. Paginated endpoints accept page and per_page parameters.

Rate Limits: Free: 30 requests/day per IP (10 per page). Authenticated: 1,000+ requests/day (50 per page). Rate limit headers included in every response.

Free Tier

No auth required
GET
/api/v1/merchants

List merchants with pagination, search, and filters. Returns limited fields.

search— Filter by domain
status— verified, not_detected, invalid, blocked, unreachable, pending
platform— Filter by platform slug
sort— domain, response_time, latest

Free response fields: domain, status, platform, capabilities_count, ucp_score, url

GET
/api/v1/products/search
New

Discover which stores carry relevant products. Returns sample products with pricing, images, and merchant metadata — use to route agents to the right store, then connect via UCP for full catalogs.

q— Search query (matches title, product type, domain, category)
category— Filter by store category (e.g. "Apparel & Accessories")
domain— Filter to a single merchant domain
min_price / max_price— Price range in dollars
sort— relevance, price_asc, price_desc, merchant
limit— Results per request (max 100, default 20)

Response: title, price, currency, url, image_url, product_type, merchant, store_category, platform + meta with totals

Authenticated Tier

API key required

All endpoints below require Authorization: Bearer YOUR_API_KEY. The merchant list endpoint also returns full fields when authenticated.

GET
/api/v1/merchants/{domain}

Get detailed merchant data including benchmark scores, capabilities, check history, and UCP endpoint.

Platforms

GET
/api/v1/platforms

List all platforms with merchant counts and average response times.

GET
/api/v1/platforms/{slug}

Get platform details including merchant count and associated entities.

Plugins

GET
/api/v1/plugins·/api/v1/plugins/{slug}

List or retrieve UCP plugins with capabilities and compatible platforms.

Tools

GET
/api/v1/tools·/api/v1/tools/{slug}

List or retrieve UCP developer tools.

Extensions

GET
/api/v1/extensions·/api/v1/extensions/{slug}

List or retrieve UCP extensions with capabilities enabled.

Vendors

GET
/api/v1/vendors·/api/v1/vendors/{slug}

List or retrieve ecosystem vendors — payment processors, logistics providers, and infrastructure companies.

Agents

GET
/api/v1/agents·/api/v1/agents/{slug}

List or retrieve AI shopping agents with funnel performance rates, efficiency metrics, and benchmark grades.

Cross-type search

GET
/api/v1/entities

Search across all entity types in a single query.

search— Search by name or domain
type— merchant, agent, platform, plugin, tool, extension, vendor
limit— Results per type (max 100, default 20)

Stats

GET
/api/v1/stats

Ecosystem-wide statistics: total merchants, agents, platforms, verified count, average response time, and more.

Need full API access?

Get an API key for complete ecosystem data — merchant endpoints, agent benchmarks, capabilities, and more.

Request API access