Skip to main content
The /.well-known/ucp file is the entry point for AI agents discovering your store. It tells agents where your product catalog, checkout, shipping, and order endpoints live. You can build this file by hand, but the Manifest Generator API creates a correctly structured manifest from your endpoint URLs, validates reachability, and flags missing optional capabilities that affect agent behaviour. All calls require authentication — see Authentication.

​
Endpoints

MethodEndpointDescription
POST/api/manifestGenerate a new manifest
POST/api/manifest/validateValidate an existing manifest URL or object

​
Generate a manifest

POST https://asva-ai.com/api/manifest

​
Request parameters

​
domain
string
required
Your store domain, without https://. Example: "yourstore.com"
​
catalog_endpoint
string
required
Full URL of your product catalog endpoint. Example: "https://yourstore.com/api/ucp/products"
​
checkout_endpoint
string
required
Full URL of your checkout creation endpoint. Example: "https://yourstore.com/api/ucp/checkout"
​
shipping_endpoint
string
Full URL of your shipping options endpoint. Declaring this allows agents to calculate shipping costs before confirming a purchase.
​
orders_endpoint
string
Full URL of your order status endpoint. Declaring this allows agents to check order status on behalf of the customer.
​
supports_search
boolean
Set to true if your catalog endpoint supports ?q= search queries. When false or omitted, agents will not attempt to search your catalog — they will only browse.
​
supports_filters
string[]
List of filter parameters your catalog endpoint accepts. Example: ["category", "price_range", "availability"]
​
supported_payment_methods
string[]
Payment methods your checkout endpoint accepts. Example: ["card", "paypal", "upi"]
Example request: 
{
  "domain": "yourstore.com",
  "catalog_endpoint": "https://yourstore.com/api/ucp/products",
  "checkout_endpoint": "https://yourstore.com/api/ucp/checkout",
  "shipping_endpoint": "https://yourstore.com/api/ucp/shipping",
  "orders_endpoint": "https://yourstore.com/api/ucp/orders",
  "supports_search": true,
  "supports_filters": ["category", "price_range", "availability"],
  "supported_payment_methods": ["card", "paypal"]
}

​
Response fields

​
version
string
Manifest schema version. Always "1.0" for current implementations.
​
generated_at
string
ISO 8601 timestamp of when this manifest was generated.
​
domain
string
The domain this manifest belongs to.
​
capabilities
object
The capability map that AI agents use to discover your endpoints.
​
capabilities.product_catalog
object
Product catalog capability, including endpoint URL, format, search support, and supported filters.
​
capabilities.checkout
object
Checkout capability, including endpoint URL, HTTP methods, authentication requirements, and supported payment methods.
​
capabilities.shipping
object
Shipping capability (present only when shipping_endpoint was provided).
​
capabilities.orders
object
Order status capability (present only when orders_endpoint was provided).
Example response: 
{
  "version": "1.0",
  "generated_at": "2026-04-10T11:00:00Z",
  "domain": "yourstore.com",
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/api/ucp/products",
      "format": "json",
      "version": "1.0",
      "supports_search": true,
      "supports_filters": ["category", "price_range", "availability"]
    },
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout",
      "supported_methods": ["POST"],
      "requires_authentication": false,
      "version": "1.0",
      "supported_payment_methods": ["card", "paypal"]
    },
    "shipping": {
      "endpoint": "https://yourstore.com/api/ucp/shipping",
      "supported_methods": ["POST"]
    },
    "orders": {
      "endpoint": "https://yourstore.com/api/ucp/orders",
      "supported_methods": ["GET", "POST"]
    }
  }
}

​
Write the manifest to .well-known/ucp

Save the API response directly to your /.well-known/ucp file. Strip generated_at so the file is stable across deployments: 
curl -s -X POST https://asva-ai.com/api/manifest \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourstore.com",
    "catalog_endpoint": "https://yourstore.com/api/ucp/products",
    "checkout_endpoint": "https://yourstore.com/api/ucp/checkout"
  }' \
  | jq 'del(.generated_at)' \
  > public/.well-known/ucp
The file at /.well-known/ucp must be served with Content-Type: application/json and must be publicly accessible without authentication.

​
Validate an existing manifest

POST https://asva-ai.com/api/manifest/validate
Use this after deploying to confirm your manifest is reachable and all declared endpoints respond correctly.

​
Request parameters

​
url
string
Public URL of your deployed manifest. Example: "https://yourstore.com/.well-known/ucp"
​
manifest
object
A manifest object to validate directly, without fetching a URL. Useful for validating before deployment.
Validate by URL: 
{
  "url": "https://yourstore.com/.well-known/ucp"
}
Validate an object directly: 
{
  "manifest": {
    "version": "1.0",
    "capabilities": {
      "product_catalog": { "endpoint": "https://yourstore.com/ucp/products" },
      "checkout": { "endpoint": "https://yourstore.com/ucp/checkout" }
    }
  }
}

​
Validation response

When valid: 
{
  "valid": true,
  "warnings": [
    "supports_search not declared — agents will not attempt catalog search queries",
    "shipping capability not declared — agents cannot calculate shipping before checkout"
  ],
  "errors": [],
  "reachability": {
    "manifest_url": "reachable",
    "catalog_endpoint": "reachable",
    "checkout_endpoint": "reachable"
  }
}
When invalid: 
{
  "valid": false,
  "errors": [
    {
      "field": "capabilities.checkout.endpoint",
      "code": "endpoint_unreachable",
      "message": "POST https://yourstore.com/ucp/checkout returned 404"
    }
  ],
  "warnings": []
}

​
Code examples

curl -X POST https://asva-ai.com/api/manifest \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourstore.com",
    "catalog_endpoint": "https://yourstore.com/api/ucp/products",
    "checkout_endpoint": "https://yourstore.com/api/ucp/checkout",
    "supports_search": true
  }'