Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asva-ai.com/llms.txt

Use this file to discover all available pages before exploring further.

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

CapabilityRequiredDescription
product_catalogYesEndpoint agents call to fetch your products
checkoutYesEndpoint agents call to create and confirm orders

​
Optional capabilities

CapabilityDescription
shippingShipping options and real-time cost calculation
ordersOrder history lookup and tracking status
returnsInitiating returns from inside the agent experience
reviewsProduct reviews and ratings for agent context

​
Hosting the manifest

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.

​
Common mistakes

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.
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.
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.
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.