UCP endpoints
The agent-facing serving-plane endpoints, governed by the external ucp.dev specification.
The endpoints AI shopping agents call are served by Sarvex’s serving plane and are deliberately not part of Sarvex’s own OpenAPI file. They conform to the external ucp.dev specification; implement against that spec.
Sarvex pins the schema types per spec generation in internal/spec/vYYYYMMDD (today 2026-04-08 and 2026-08-25), and tracks deviations in each generation’s DISCREPANCIES.md. A profile advertises which generation and capabilities a store serves; agents negotiate against it.
Endpoints
| Method + path | Purpose |
|---|---|
GET /.well-known/ucp |
The business profile. Served from the merchant’s own domain by the plugin, with Sarvex’s bytes. |
POST /catalog/search |
Catalog search (served from cache only). |
GET /catalog/{itemId} |
Product lookup (cache only). |
POST /checkout-sessions |
Create a checkout session (live stock and pricing). |
GET /checkout-sessions/{checkoutId} |
Read session state. |
PUT /checkout-sessions/{checkoutId} |
Full-replacement update (buyer, fulfillment, selection). |
POST /checkout-sessions/{checkoutId}/complete |
Accept an opaque payment credential reference plus handler_id; create the order. |
POST /checkout-sessions/{checkoutId}/cancel |
Cancel a non-terminal session (idempotent). |
GET /orders/{orderId} / PUT /orders/{orderId} |
Read an order; append fulfillment events or adjustments. |
Base path is the services.endpoint published in the profile.
Guarantees worth knowing
- Discovery and catalog reads never call the store. They read only the serving cache. Checkout is the one exception: it calls the merchant backend live, only through the sync-plane connector.
- Idempotent mutations. Checkout mutations require idempotency keys; retries are the normal case.
- No raw credentials. The checkout schema has no field able to hold a payment credential — only opaque references and a
handler_id. - Signed requests. Agent identity is ECDSA request signing per UCP / RFC 9421, not API keys (ADR-0001).
For the internals see Architecture, and for the wire-level schemas the spec modules under internal/spec/.