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

Sarvex V1 API

Control-plane API for Sarvex V1 — the authenticated surface behind the merchant console, the operator tooling, and the store-connector ingest endpoint.

Scope of this document

This specification covers the control plane and the sync-plane ingest edge (/connector/*). It deliberately does not specify the serving plane (the UCP edge: profile, discovery, pricing, availability, shipping, and the three checkout-session operations). Those endpoints conform to the published UCP / Google UCP-checkout schemas — they are governed by an external specification, not by Sarvex’s own contract, and are versioned against the UCP spec version recorded per merchant in conformance_record. See the backend architecture document, Domains 4–5.

Conventions (true for every operation)

  • Tenant scoping: merchant_id is never a path or query parameter. It is read from the authenticated principal’s token claim server-side, so a token can only ever reach its own tenant’s data. Operators select a merchant via the X-Operate-As header (see security schemes), which is audit-logged.
  • Wire format: all request and response bodies are JSON with snake_case field names.
  • List envelope: all collection responses are { "data": [...], "page": { "cursor": string|null, "has_more": boolean } }.
  • Error envelope: all non-2xx responses are { "error": { "code": string, "message": string, "details": object|null } }.
  • Pagination: cursor-based via the cursor query parameter; limit caps page size.
  • Idempotency: all mutating operations accept an Idempotency-Key header; replays return the original result.
  • Money: integer minor units (cents) plus an ISO-4217 currency field; never floats.
  • Timestamps: RFC 3339 / ISO 8601 UTC strings.
Version 1.0.0
Base URLhttps://api.sarvex.example.com/v1https://api.staging.sarvex.example.com/v1

Contact

Marketing-site contact-form ingest (sarvex.example.com). Not merchant/operator-authenticated — gated by a shared bearer token issued to the website only, scoped to this one endpoint.

Auth

Resolving the principal from the externally-issued, Sarvex-verified JWT. No login/logout — authentication is handled by the IdP (OAuth 2.0 authorization-code flow).

Account

Merchant profile and Google-required business facts.

Stores

The stores a merchant operates (merchant → store → connector). One in V1, modelled for many.

Payment

Per-store payment-handler configuration (instruments vs handlers model).

Connectors

Store connection, pairing, health. A connector belongs to a store.

Connector Ingest

Sync-plane-served endpoints bundled here by convention. These /connector/* paths are actually served by the sync plane (not the control plane); they are included in this spec for operational convenience (a single auth token reaches both control and sync). Covered operations: plugin-facing ingest (HMAC-signed). Covers both plugin roles: change signals (push) and the profile fetch the plugin serves at the merchant origin (Role 2). The plugin does not proxy the UCP API — the profile’s endpoint points directly at Sarvex.

Catalog

Readiness score, products, attribute mappings.

Tasks

The task spine — every actionable item, by owner.

Remediation

Rule-based fixes and reversible write-backs.

Validation

Pre-validation, sandbox, and production validation status.

UCP Presence

Read-only view of the hosted profile and manifest.

Orders

Orders created via Google checkout and their status sync.

Health

Post-go-live integration health and consistency.

Checkout Sessions

Checkout Escalation Console — session projection, event timeline, and diagnosis for stalled or escalated checkouts.

Ledger

Lost Revenue Ledger — classified, priced, per-store visibility into checkouts that didn’t convert.

Channel Dashboard

Agent sessionization, discovery→checkout funnel, and web-baseline comparison for the merchant’s UCP-powered checkout channel — what it’s earning and how it compares to the web channel.

Agent Behavior Insights

Billing

Plan, usage, and Stripe-hosted management links.

Notifications

Channel preferences for the fixed V1 alert set.

Activation

The store’s own UCP activation lifecycle — profile served, capabilities declared, signatures verifying, checkout working. Sarvex and the merchant only: nothing in this lifecycle references feeds or any other agent surface. active is the terminal success state and is complete on its own; a store may sit there with zero surfaces enrolled indefinitely.

Surfaces

Agent-surface enrollment — per-store, zero-to-many, registry-driven. A surface is declared as a descriptor (requirements, prerequisite checks, artifacts, external steps, verification signal); adding one is a descriptor plus its adapters, never a change to these endpoints. The only dependency on activation runs one way: enrollment cannot progress past available unless the store is active. Surfaces never gate each other.

Journey

The per-store onboarding state machine.

Operator

Operator-only provisioning (create merchant, invite member, create store), board, enter-as-merchant, audit, manual-step capture.

Was this page helpful?