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

Capabilities agents requested that the merchant doesn't declare

The headline output: for each capability agents’ negotiation requests actually named, minus the capabilities the merchant declares in their UCP profile. Sorted by estimated_impact_minor descending, request_count descending as tiebreak, unconditionally — there is no sort query parameter, the same money-first invariant the Lost Revenue Ledger enforces on its own default sort. estimated_impact_minor is 0 with impact_confidence=unmeasurable unless a specific failed/abandoned checkout’s cart snapshot could be demonstrably attributed to the missing capability — never a modeled or extrapolated figure. Rows with request_count below the small-count suppression threshold (default 5) are omitted.

GET/insights/capability_gaps
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.

Query parameters
monthstring

yyyy-MM. Defaults to the current UTC month.

store_idstring

Restrict to one store. Omit for every store the merchant operates.

Responses
200

Capability gaps for the month, impact-sorted.

datainsights_capability_gap[]required
Show properties
Array of insights_capability_gap
capability_idstring

A reverse-domain capability name taken verbatim from the negotiation's requested capability set (internal/pkg/ucp/types) — never free-form.

request_countinteger
distinct_agent_countinteger

Count of distinct calling agent platforms (by negotiation platform_profile_uri) observed requesting this capability — the closest honest proxy this telemetry supports for "distinct agent" (no per-buyer or per-conversation identity exists on the wire).

surface_breakdownobject
first_seen_atstring<date-time>
last_seen_atstring<date-time>
estimated_impact_minorinteger
impact_confidenceinsights_impact_confidence

measured: every session counted toward estimated_impact_minor had a cart snapshot demonstrably preceded by the missing capability. partial: some but not all counted sessions had a cart snapshot. unmeasurable: no session could be demonstrably attributed — estimated_impact_minor is 0, never a modeled or extrapolated figure (same no-estimation rule as the Lost Revenue Ledger).

Allowed:measuredpartialunmeasurable
merchant_supportedboolean

Whether the merchant declares this capability — always false for a row that exists at all (a gap is by construction requested-minus-declared), kept as a stored, queryable field rather than an implied invariant.

remediation_availableboolean

Whether Sarvex can close this gap on the merchant's behalf. Always false today — nothing in this codebase lets Sarvex serve a UCP capability for a merchant; every gap requires merchant-side work.

recommended_actionstring

Merchant-readable, imperative, no protocol jargon.

pagepagerequired
Show properties
cursorstring | nullrequired
has_morebooleanrequired
403

Authenticated but not permitted (e.g. non-operator on an operator route).

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
422

Request body failed validation.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.sarvex.example.com/v1/insights/capability_gaps" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "data": [
    {
      "capability_id": "string",
      "request_count": 0,
      "distinct_agent_count": 0,
      "surface_breakdown": {
        "property1": 0,
        "property2": 0
      },
      "first_seen_at": "2019-08-24T14:15:22Z",
      "last_seen_at": "2019-08-24T14:15:22Z",
      "estimated_impact_minor": 0,
      "impact_confidence": "measured",
      "merchant_supported": true,
      "remediation_available": true,
      "recommended_action": "string"
    }
  ],
  "page": {
    "cursor": "string",
    "has_more": true
  }
}