UCP Capability Discovery: Hosting .well-known/ucp

Before an AI agent can browse your catalog or place an order, it needs to know what your store supports and where to call it. The /.well-known/ucp file is that declaration. When a UCP-compatible platform — Google AI Mode, Gemini, or any other agent — encounters your domain, it fetches this file first. Without it, agents cannot discover or transact with you at all.

The manifest must be served at https://yourdomain.com/.well-known/ucp (or /.well-known/ucp.json) with Content-Type: application/json and no authentication required. Agents will not send credentials to fetch capability discovery files.

Minimal manifest

The minimum valid manifest requires a product_catalog capability and a checkout capability. Both must include an endpoint URL.

/.well-known/ucp

{
  "version": "1.0",
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/api/ucp/products"
    },
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout"
    }
  }
}

Full manifest with all capabilities

Declare optional capabilities to unlock additional agent behaviors — shipping cost calculation, order tracking, and return initiation.

/.well-known/ucp

{
  "version": "1.0",
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/api/ucp/products",
      "format": "json",
      "version": "1.0",
      "supports_search": true,
      "supports_filters": ["category", "price", "availability"]
    },
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout",
      "supported_methods": ["POST"],
      "requires_authentication": false,
      "version": "1.0"
    },
    "shipping": {
      "endpoint": "https://yourstore.com/api/ucp/shipping",
      "supported_methods": ["POST"]
    },
    "orders": {
      "endpoint": "https://yourstore.com/api/ucp/orders",
      "supported_methods": ["GET", "POST"]
    },
    "returns": {
      "endpoint": "https://yourstore.com/api/ucp/returns",
      "supported_methods": ["POST"]
    }
  }
}

Required capabilities

Capability	Required	Description
`product_catalog`	Yes	Endpoint agents call to fetch your products
`checkout`	Yes	Endpoint agents call to create and confirm orders

Optional capabilities

Capability	Description
`shipping`	Shipping options and real-time cost calculation
`orders`	Order history lookup and tracking status
`returns`	Initiating returns from inside the agent experience
`reviews`	Product reviews and ratings for agent context

Hosting the manifest

Next.js / Vercel
Express.js
Nginx
Shopify

Place the file at public/.well-known/ucp. Next.js serves everything in public/ as static files automatically.

mkdir -p public/.well-known

Then create public/.well-known/ucp with your manifest JSON. No additional configuration required — Vercel will serve it at /.well-known/ucp.

Vercel sets Content-Type based on file extension. Since ucp has no extension, verify the response header is application/json. You may need a vercel.json rewrite rule or a Route Handler to set the header explicitly.

Serve the manifest from a route handler so the Content-Type header is always correct:

app.get('/.well-known/ucp', (req, res) => {
  res.json({
    version: '1.0',
    capabilities: {
      product_catalog: { endpoint: `${process.env.BASE_URL}/api/ucp/products` },
      checkout: { endpoint: `${process.env.BASE_URL}/api/ucp/checkout` }
    }
  })
})

Alias the path to a static JSON file on disk:

location /.well-known/ucp {
  default_type application/json;
  alias /var/www/html/.well-known/ucp.json;
}

Common mistakes

404 — file not at domain root

The manifest must be at https://yourdomain.com/.well-known/ucp, not on a subdomain like shop.yourdomain.com/.well-known/ucp. Check that your web server routes the root domain correctly, and that .well-known directories aren’t blocked by a .htaccess or server config.

JSON parse error

Validate your JSON before deploying. Common causes: trailing commas, unescaped quotation marks inside strings, or missing closing brackets.

cat .well-known/ucp | python3 -m json.tool

If the command exits without output, your JSON is valid.

Wrong Content-Type header

The response must include Content-Type: application/json. Some static hosts serve unknown file extensions as text/plain. Override this in your hosting configuration — see the Nginx and Express examples above.

Endpoint is behind authentication

The /.well-known/ucp file must be publicly accessible with no API key, cookie, or auth header required. AI agents follow the .well-known convention and will not authenticate to fetch this file.

Validate with Asva

Use the Manifest Generator and Validator to generate a compliant manifest from your endpoint URLs, validate the JSON of an existing file, and confirm your hosted manifest is publicly reachable. To validate via the API:

curl -X POST https://asva-ai.com/api/audit \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourstore.com", "checks": ["well_known"]}'

Next steps

Product catalog endpoint

Structure your catalog endpoint so agents can find the right product and variant.

Checkout and payments

Implement cart creation and order confirmation.

Get Started

UCP

ACP

Attribution

Guides

UCP Capability Discovery: Hosting .well-known/ucp

Minimal manifest

Full manifest with all capabilities

Required capabilities

Optional capabilities

Hosting the manifest

Common mistakes

Validate with Asva

Next steps

Product catalog endpoint

Checkout and payments

​Minimal manifest

​Full manifest with all capabilities

​Required capabilities

​Optional capabilities

​Hosting the manifest

​Common mistakes

​Validate with Asva

​Next steps

Product catalog endpoint

Checkout and payments

Minimal manifest

Full manifest with all capabilities

Required capabilities

Optional capabilities

Hosting the manifest

Common mistakes

Validate with Asva

Next steps