Skip to content
SarvexDocs
Esc
↑↓navigate↵open⌘Jpreview

Fetch the merchant's current UCP profile (for the plugin to serve at /.well-known/ucp)

Called by the plugin (Role 2 — origin-correct doorway), not by agents. Returns the exact UCP business-profile bytes Sarvex generates and signs; the plugin serves these verbatim from the merchant’s own domain at /.well-known/ucp with a 200. The merchant is resolved from the HMAC credential — no URL parameter.

Conditional fetch: the plugin sends If-None-Match with the ETag it last received; if the profile is unchanged Sarvex returns 304 Not Modified and the plugin keeps serving its cached copy. Steady state is a cheap 304 on most calls. The Cache-Control header tells the plugin how long its copy is valid; past that (or on must-revalidate) it refetches. If this endpoint is unreachable, the plugin serves its last-known-good copy (degradation ladder, profile edge) — the profile must never disappear or error at the merchant origin.

This endpoint covers only the profile. The /ucp/v1/* UCP API is served by Sarvex directly — the profile’s services.endpoint points at Sarvex, so agents call the serving plane straight after discovery. The plugin does not proxy API traffic.

GET/connector/profile
Authorization
X-Sarvex-SignatureAPI key · headerrequired

HMAC-SHA256 signature over the raw request body plus the X-Sarvex-Timestamp and X-Sarvex-Sequence headers, keyed by the per-connector signing secret issued at pairing. Used only by the store plugin for /connector/*. Replays (seen sequence) are rejected with 409.

Header parameters
If-None-Matchstring

The ETag the plugin last received; enables a 304 when unchanged.

Responses
200

Current profile document. Serve verbatim at /.well-known/ucp.

ucpobject
Show properties
versionstring

The newest UCP spec generation Sarvex's protocol layer (negotiation, discovery envelope) fully supports — not a claim that every capability below is rendered at this version. Each capability entry carries its own version independently; per-capability negotiation picks the highest version mutually supported by the platform and by that specific capability's own declared entries.

servicesobject

Keyed by service namespace (e.g. dev.ucp.shopping), each with spec + rest endpoint.

capabilitiesobject[]

Supported capabilities and extensions, each a ucp.dev namespaced name + version + schema URL. A capability may appear more than once under the same name at different versions when Sarvex can render more than one (e.g. catalog, at both 2026-04-08 and 2026-08-25) — a capability whose response-building hasn't caught up to the document's top-level version (e.g. checkout, still 2026-04-08 only) declares just the one it can actually serve.

payment_handlersobject[]

Supported handlers (e.g. Google Pay, Shop Pay) the merchant's setup supports, with keys/endpoints.

keysobject[]

Sarvex's public signing keys (a JWK Set), matching the keys the serving plane signs responses with. Named "keys" from the 2026-08-25 generation on; a document declaring an older ucp.version instead uses the legacy "signing_keys" field name — the two are mutually exclusive per document.

304

Profile unchanged since the supplied ETag; plugin keeps serving its cache.

401

Missing or invalid credentials.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
409

No servable profile yet (merchant not far enough through onboarding).

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.sarvex.example.com/v1/connector/profile" \
  -H "X-Sarvex-Signature: YOUR_API_KEY"
Response
{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "property1": {},
      "property2": {}
    },
    "capabilities": [
      {}
    ],
    "payment_handlers": [
      {}
    ],
    "keys": [
      {}
    ]
  }
}