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

Replace the merchant-supplied configuration for a surface

The configuration is a string map by design: its shape is the surface’s own business, declared by the descriptor’s config_schema, so typing it here would put surface-specific knowledge into the generic layer. A surface that declares a schema has the map validated against it (unknown keys and ill-typed values are a 422); one that declares none accepts any map. Prerequisites are re-evaluated against the new configuration before the response is returned.

PUT/stores/{store_id}/surfaces/{surface_id}/config
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.

Path parameters
store_idstringrequired

A store the caller's merchant owns. Authorized server-side against the principal; not a free-form tenant selector.

surface_idstringrequired

A surface id from the registry (GET /surfaces). Not a tenant selector — enrollment is always scoped to the caller's merchant server-side.

Request body
requiredapplication/json
configobject
Responses
200

Enrollment state after configuration.

surface_idstringrequired
store_idstringrequired
statesurface_staterequired

A store's enrollment position on one agent surface (internal/planes/control/surface). Per-store, per-surface, zero-to-many.

Allowed:availableprerequisites_pendingconfiguredsubmittedverifyingenrolledsuspended
prerequisitesprerequisite_result[]required
Show properties
Array of prerequisite_result
check_idstringrequired
label_keystringrequired
passedbooleanrequired
reasonstring

Merchant-readable explanation of a failure. Empty on pass.

remediation_keystring

vue-i18n key for the fix, where one applies.

remediation_urlstring<uri>
evaluated_atstring<date-time>required
artifactssurface_artifact[]required
Show properties
Array of surface_artifact
artifact_idstringrequired
label_keystringrequired
urlstring<uri>
detailobject

Artifact-specific read-only facts for display. Rendered generically as label/value rows.

generated_atstring<date-time>
configobject
enrolled_atstring<date-time>
last_verified_atstring<date-time>
suspension_reasonstring
updated_atstring<date-time>required
descriptorobjectrequired

Echoed alongside state so a client renders the whole enrollment flow from one response, with no per-surface knowledge of its own.

Show properties
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.

blockedbooleanrequired

True when the store is not yet active — the one thing that holds enrollment at available.

blocked_reasonstring

i18n key.

404

Resource not found within the caller's tenant.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
409

Store is not UCP active.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
422

Request body failed validation.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X PUT "https://api.sarvex.example.com/v1/stores/string/surfaces/string/config" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "config": {
    "property1": "string",
    "property2": "string"
  }
}'
Response
{
  "surface_id": "string",
  "store_id": "string",
  "state": "available",
  "prerequisites": [
    {
      "check_id": "string",
      "label_key": "string",
      "passed": true,
      "reason": "string",
      "remediation_key": "string",
      "remediation_url": "http://example.com",
      "evaluated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "artifacts": [
    {
      "artifact_id": "string",
      "label_key": "string",
      "url": "http://example.com",
      "detail": {
        "property1": "string",
        "property2": "string"
      },
      "generated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "config": {
    "property1": "string",
    "property2": "string"
  },
  "enrolled_at": "2019-08-24T14:15:22Z",
  "last_verified_at": "2019-08-24T14:15:22Z",
  "suspension_reason": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "descriptor": {
    "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
  },
  "blocked": true,
  "blocked_reason": "string"
}