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

List the surface registry

Every surface this deployment knows about, as descriptors. Not store-scoped: which surfaces exist is a property of the deployment, not of a merchant. What a particular store has done about them is GET /stores/{store_id}/surfaces.

GET/surfaces
Authorization
AuthorizationBearer token (JWT) · headerrequired

JWT issued by the external IdP via the OAuth 2.0 authorization-code flow (Kinde in production; a simulator in test). The client obtains it and sends it as a Bearer token on every authenticated call. Sarvex's services verify it — issuer, audience, signature (IdP JWKS), expiry — and read identity and tenant from its claims. Sarvex does not issue or revoke these tokens. merchant_id/store_id are read from the verified claims (and the merchant→store mapping), never from the URL. The operator scope is required for /operator/*. Operators acting on a specific merchant pass the X-Operate-As header, which is recorded in the audit log.

Responses
200

Registered surface descriptors.

datasurface_descriptor[]required
Show properties
Array of surface_descriptor
surface_idstringrequired
display_name_keystringrequired
description_keystring
protocolsurface_protocolrequired

The wire protocol an agent surface speaks. Data on the descriptor, never a branch in code.

Allowed:ucpacp
required_connectorsconnector_type[]
required_capabilitiesstring[]

Canonical UCP capability identifiers only. A free-form value is rejected at registry construction.

prerequisite_checksstring[]

Named checks, in the order the merchant sees them. Each resolves to an adapter at registration.

artifactsstring[]

Sarvex-generated, surface-scoped artifacts. Generated only for stores enrolling in this surface.

config_schemasurface_config_field[]

The merchant-editable configuration this surface takes. The console renders a form from it with no per-surface code. Empty means free-form (or no) config. When non-empty, PUT .../config rejects unknown keys and ill-typed values with a validation error.

Show properties
Array of surface_config_field
keystringrequired
typestringrequired

text; bool ("true"/"false"); string_list (newline-separated); json (a JSON document). Values are always strings on the wire.

Allowed:textboolstring_listjson
label_keystringrequired

vue-i18n key.

help_keystring

vue-i18n key for help text.

requiredbooleanrequired

Advisory — a missing required value is a failing prerequisite, not a rejected request.

external_stepssurface_external_step[]
Show properties
Array of surface_external_step
step_idstringrequired
label_keystringrequired

vue-i18n key. The descriptor owns identity, the console owns copy.

urlstring<uri>
ownerstringrequired

Who the step waits on, so a client renders waiting states without surface-specific knowledge.

Allowed:merchantsurface
verification_signalstring

Names what proves enrollment succeeded.

auto_enrollboolean

True for a surface that enrolls itself when the store reaches active. direct_agent is the only such surface: it represents the plain fact that any agent discovering the profile can transact, and exists so that "active with no distribution partner" is explicit rather than implied.

pagepagerequired
Show properties
cursorstring | nullrequired
has_morebooleanrequired
Try it
Server
Authorization
Request
curl -X GET "https://api.sarvex.example.com/v1/surfaces" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "data": [
    {
      "surface_id": "string",
      "display_name_key": "string",
      "description_key": "string",
      "protocol": "ucp",
      "required_connectors": [
        "commerce"
      ],
      "required_capabilities": [
        "string"
      ],
      "prerequisite_checks": [
        "string"
      ],
      "artifacts": [
        "string"
      ],
      "config_schema": [
        {
          "key": "string",
          "type": "text",
          "label_key": "string",
          "help_key": "string",
          "required": true
        }
      ],
      "external_steps": [
        {
          "step_id": "string",
          "label_key": "string",
          "url": "http://example.com",
          "owner": "merchant"
        }
      ],
      "verification_signal": "string",
      "auto_enroll": true
    }
  ],
  "page": {
    "cursor": "string",
    "has_more": true
  }
}