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

# Manifest Generator API: POST /api/manifest Reference

> Generate a standards-compliant /.well-known/ucp manifest from your endpoint URLs, then validate an existing manifest for reachability and completeness.

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](/api-reference/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

<ParamField body="domain" type="string" required>
  Your store domain, without `https://`. Example: `"yourstore.com"`
</ParamField>

<ParamField body="catalog_endpoint" type="string" required>
  Full URL of your product catalog endpoint. Example: `"https://yourstore.com/api/ucp/products"`
</ParamField>

<ParamField body="checkout_endpoint" type="string" required>
  Full URL of your checkout creation endpoint. Example: `"https://yourstore.com/api/ucp/checkout"`
</ParamField>

<ParamField body="shipping_endpoint" type="string">
  Full URL of your shipping options endpoint. Declaring this allows agents to calculate shipping costs before confirming a purchase.
</ParamField>

<ParamField body="orders_endpoint" type="string">
  Full URL of your order status endpoint. Declaring this allows agents to check order status on behalf of the customer.
</ParamField>

<ParamField body="supports_search" type="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.
</ParamField>

<ParamField body="supports_filters" type="string[]">
  List of filter parameters your catalog endpoint accepts. Example: `["category", "price_range", "availability"]`
</ParamField>

<ParamField body="supported_payment_methods" type="string[]">
  Payment methods your checkout endpoint accepts. Example: `["card", "paypal", "upi"]`
</ParamField>

**Example request:**

```json theme={null}
{
  "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

<ResponseField name="version" type="string">
  Manifest schema version. Always `"1.0"` for current implementations.
</ResponseField>

<ResponseField name="generated_at" type="string">
  ISO 8601 timestamp of when this manifest was generated.
</ResponseField>

<ResponseField name="domain" type="string">
  The domain this manifest belongs to.
</ResponseField>

<ResponseField name="capabilities" type="object">
  The capability map that AI agents use to discover your endpoints.

  <ResponseField name="capabilities.product_catalog" type="object">
    Product catalog capability, including endpoint URL, format, search support, and supported filters.
  </ResponseField>

  <ResponseField name="capabilities.checkout" type="object">
    Checkout capability, including endpoint URL, HTTP methods, authentication requirements, and supported payment methods.
  </ResponseField>

  <ResponseField name="capabilities.shipping" type="object">
    Shipping capability (present only when `shipping_endpoint` was provided).
  </ResponseField>

  <ResponseField name="capabilities.orders" type="object">
    Order status capability (present only when `orders_endpoint` was provided).
  </ResponseField>
</ResponseField>

**Example response:**

```json theme={null}
{
  "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:

```bash theme={null}
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
```

<Note>
  The file at `/.well-known/ucp` must be served with `Content-Type: application/json` and must be publicly accessible without authentication.
</Note>

***

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

<ParamField body="url" type="string">
  Public URL of your deployed manifest. Example: `"https://yourstore.com/.well-known/ucp"`
</ParamField>

<ParamField body="manifest" type="object">
  A manifest object to validate directly, without fetching a URL. Useful for validating before deployment.
</ParamField>

**Validate by URL:**

```json theme={null}
{
  "url": "https://yourstore.com/.well-known/ucp"
}
```

**Validate an object directly:**

```json theme={null}
{
  "manifest": {
    "version": "1.0",
    "capabilities": {
      "product_catalog": { "endpoint": "https://yourstore.com/ucp/products" },
      "checkout": { "endpoint": "https://yourstore.com/ucp/checkout" }
    }
  }
}
```

### Validation response

**When valid:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "valid": false,
  "errors": [
    {
      "field": "capabilities.checkout.endpoint",
      "code": "endpoint_unreachable",
      "message": "POST https://yourstore.com/ucp/checkout returned 404"
    }
  ],
  "warnings": []
}
```

***

## Code examples

<CodeGroup>
  ```bash cURL — Generate theme={null}
  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
    }'
  ```

  ```bash cURL — Validate URL theme={null}
  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"}'
  ```

  ```typescript TypeScript theme={null}
  // 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)
  }
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

***

## Related

* [Manifest Generator tool](https://asva-ai.com/tools/manifest) — browser UI version of this API
* [.well-known manifest deep dive](/ucp/manifest-deep-dive) — full manifest spec and advanced options
* [Readiness API](/api-reference/readiness) — full domain audit including manifest validation