Manifest Generator API: POST /api/manifest Reference

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

Method	Endpoint	Description
`POST`	`/api/manifest`	Generate a new manifest
`POST`	`/api/manifest/validate`	Validate an existing manifest URL or object

Generate a manifest

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

Request parameters

string

required

Your store domain, without https://. Example: "yourstore.com"

string

required

Full URL of your product catalog endpoint. Example: "https://yourstore.com/api/ucp/products"

string

required

Full URL of your checkout creation endpoint. Example: "https://yourstore.com/api/ucp/checkout"

string

Full URL of your shipping options endpoint. Declaring this allows agents to calculate shipping costs before confirming a purchase.

string

Full URL of your order status endpoint. Declaring this allows agents to check order status on behalf of the customer.

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.

string[]

List of filter parameters your catalog endpoint accepts. Example: ["category", "price_range", "availability"]

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

string

Manifest schema version. Always "1.0" for current implementations.

string

ISO 8601 timestamp of when this manifest was generated.

string

The domain this manifest belongs to.

object

The capability map that AI agents use to discover your endpoints.

object

Product catalog capability, including endpoint URL, format, search support, and supported filters.

object

Checkout capability, including endpoint URL, HTTP methods, authentication requirements, and supported payment methods.

object

Shipping capability (present only when shipping_endpoint was provided).

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

string

Public URL of your deployed manifest. Example: "https://yourstore.com/.well-known/ucp"

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
  }'

curl -X POST https://asva-ai.com/api/manifest/validate \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourstore.com/.well-known/ucp"}'

// Generate
const manifest = await fetch('https://asva-ai.com/api/manifest', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ASVA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    domain: 'yourstore.com',
    catalog_endpoint: 'https://yourstore.com/api/ucp/products',
    checkout_endpoint: 'https://yourstore.com/api/ucp/checkout'
  })
}).then(r => r.json())

// Validate
const validation = await fetch('https://asva-ai.com/api/manifest/validate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ASVA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: 'https://yourstore.com/.well-known/ucp' })
}).then(r => r.json())

if (!validation.valid) {
  console.error('Manifest errors:', validation.errors)
}

import requests
import json

# Generate
manifest = requests.post(
    'https://asva-ai.com/api/manifest',
    headers={'Authorization': f'Bearer {ASVA_API_KEY}'},
    json={
        'domain': 'yourstore.com',
        'catalog_endpoint': 'https://yourstore.com/api/ucp/products',
        'checkout_endpoint': 'https://yourstore.com/api/ucp/checkout'
    }
).json()

# Save to file
with open('public/.well-known/ucp', 'w') as f:
    manifest.pop('generated_at', None)
    json.dump(manifest, f, indent=2)

Manifest Generator tool — browser UI version of this API
.well-known manifest deep dive — full manifest spec and advanced options
Readiness API — full domain audit including manifest validation

​Endpoints

​Generate a manifest

​Request parameters

​Response fields

​Write the manifest to .well-known/ucp

​Validate an existing manifest

​Request parameters

​Validation response

​Code examples

​Related

Endpoints

Generate a manifest

Request parameters

Response fields

Write the manifest to .well-known/ucp

Validate an existing manifest

Request parameters

Validation response

Code examples

Related