Discovery + manifest
Publish one machine-readable shop profile so agents know what your store can sell and how checkout works.
The host-aware .well-known/ucp document — capabilities, endpoints, signing keys, auth modes.
Every UCP-aware store publishes a single discovery document at /.well-known/ucp. An agent reads that doc once, learns which capabilities exist and at which URLs, and stops needing to know anything Aly-specific.
Request
bash
curl https://acme.aly.store/.well-known/ucpHost-aware response
The response branches on the request Host header:
- Platform host (
aly.store) — returns the platform manifest, with catalog search that crosses all published sites. - Store host (
<slug>.aly.storeor a verified custom domain) — returns the store manifest, pre-bound to the site so calls can omitsite_slug. - Unknown host — falls back to the platform manifest. Discovery never 404s, so a typo doesn't break the agent loop.
Shape
json
{ "ucp": { "version": "1" }, "service": "dev.ucp.shopping", "name": "Acme Store", "issuer": "https://acme.aly.store", "capabilities": [ "dev.ucp.shopping.checkout", "dev.ucp.shopping.catalog.search", "dev.ucp.shopping.catalog.lookup", "dev.ucp.shopping.discount", "dev.ucp.shopping.buyer_consent", "dev.ucp.shopping.fulfillment", "dev.ucp.shopping.order", "dev.ucp.common.identity_linking" ], "endpoints": { "catalog_search": "https://aly.store/api/ucp/v1/catalog/search", "catalog_lookup": "https://aly.store/api/ucp/v1/catalog/lookup", "checkout_create": "https://aly.store/api/ucp/v1/checkout-sessions", "checkout_get_pattern": "https://aly.store/api/ucp/v1/checkout-sessions/{id}", "order_get_pattern": "https://aly.store/api/ucp/v1/orders/{id}", "agent_card": "https://acme.aly.store/.well-known/agent-card.json" }, "site": { "slug": "acme", "currency": "USD" }, "auth": { "modes": ["guest", "bearer"], "oauth_metadata": "https://aly.store/.well-known/oauth-authorization-server" }, "signing": { "jwks_uri": "https://aly.store/.well-known/ucp/jwks.json", "request_signature_required": false }}Capabilities reference
| Capability id | Meaning |
|---|---|
dev.ucp.shopping.checkout | Create/read/update/complete checkout sessions. |
dev.ucp.shopping.catalog.search | Catalog full-text + filter search. |
dev.ucp.shopping.catalog.lookup | Batch product lookup by id. |
dev.ucp.shopping.discount | Apply discount/coupon codes. |
dev.ucp.shopping.buyer_consent | Capture buyer's consent for shipping / terms. |
dev.ucp.shopping.fulfillment | Fulfillment events visible via order endpoint. |
dev.ucp.shopping.order | Order retrieval after checkout. |
dev.ucp.common.identity_linking | Link an agent identity to the request via JWS. |
Cache the manifest
Discovery returns a one-hour
Cache-Control. Agents that chat with the same store repeatedly should cache the manifest and invalidate on capability-version bumps.Related discovery documents
GET /.well-known/protocols— Hub doc listing MCP, UCP, A2A, OAuth, OpenAPI all in one place.GET /.well-known/agent-card.json— A2A agent card for the same store/platform.GET /.well-known/oauth-authorization-server— RFC 8414 OAuth metadata.
Was this page helpful?