Reference

Action previews

Preview, confirmation, idempotency, metering, audit, and refusal behavior for approved actions.

On this page

Intent lifecycle #

For preview_or_execute operations, the lifecycle is preview -> confirm -> execute. Execute without the required matching preview and confirmation is refused. This lifecycle does not apply to read_only, handoff_only, or direct create_resource operations.

Stage	What happens
Preview	A preview explains the target, current configuration, possible side effects, the authority required, and the idempotency key that will carry into execute.
Confirm	A human or authorized agent confirms the exact action inside the grant and product boundary.
Execute	FlowRelay performs the action, records audit context, and returns the result or refusal.

Actions that need previews #

Use action previews for replay, diagnostics sharing, endpoint edits, secret rotation, endpoint deletion, and support request preview/submit. Each records audit context on execute or refusal. Endpoint creation and expansion or feature requests are direct create_resource operations and do not use this lifecycle; endpoint-test intent is handoff_only and returns sender-owned test instructions rather than sending traffic.

Direct creation and support submission #

Endpoint creation executes when the scoped request is accepted and returns its new secret once. Expansion and feature requests record non-binding request resources directly with expansion:request scope. Support request preview and submit use explicit request states, consent, redaction, and idempotency, but the API does not claim that submit is coupled to a persisted matching-preview record.

Idempotency #

Carry the same idempotency key from preview to execute. Generate a fresh preview, and a new key, if the target, payload, endpoint, event, or actor changes. Reusing a key after any of these changes is refused.

Metering #

FlowRelay counts action previews separately from executed actions. Repeated preview loops can hit short-window rate limits or sustained fair-use review even when no action is executed, so check plan usage before broad reads, polling, or repeated previews.

Audit and refusals #

Audit preserves who previewed, who confirmed, what was executed, and which grant allowed it. Refusals explain the missing scope, unsafe state, expired retention, usage limit, or product boundary.

Custom endpoint configuration operations #

When the manifest advertises the capability, POST /agent/v1/endpoint-configurations/preview accepts endpointId, processingConfig, and an operator-supplied synthetic sample. It reads no retained event and uses no event or action allowance. Use setup:read; per-installation abuse limits still apply. POST /agent/v1/endpoint-configurations/export accepts endpointIds (1–20) and counts as a rich Agent read. Review literals and authentication requirements in the resulting file before sharing it.

POST /agent/v1/endpoint-configurations/intents supports processing, activation, and import with setup:read plus endpoint:write. POST /agent/v1/endpoint-configurations/credential-intents supports rotation and previous-key revocation with setup:read plus secret:rotate. Each requires a preview then explicit confirmation using the same idempotencyKey. Preview expires after 30 minutes; endpoint revision changes require another preview. Repeated execution returns a receipt without repeating the mutation or revealing the credential again. Human sender-owned secret entry is unavailable to agents.

CLI commands are endpoint-data-preview, endpoint-export, endpoint-configuration-intent, and endpoint-credential-intent. Supply JSON with --json FILE or stdin. MCP tools use these same operations, scopes, confirmations, and meters; the read-only Shopify Sidekick extension remains unchanged. Saving configuration does not configure or prove a Shopify workflow.

Preview a settings change: request body

{
  "state": "preview",
  "idempotencyKey": "synthetic-configuration-001",
  "configuration": {
    "operation": "processing",
    "endpointId": "<owned-endpoint-id>",
    "revision": 1,
    "processingConfig": {
      "schemaVersion": 1,
      "engineVersion": "jsonata-2.2.2/flr-1",
      "mode": "simple",
      "fields": [
        {
          "name": "message",
          "sourcePath": "message",
          "schema": {
            "type": "string"
          }
        }
      ]
    }
  }
}

Confirm only after reviewing the response

{
  "state": "execute",
  "idempotencyKey": "synthetic-configuration-001",
  "confirmed": true
}

Equivalent CLI calls; credential comes from the private profile

npx flowrelay-agent endpoint-data-preview --json synthetic-sample.json
npx flowrelay-agent endpoint-configuration-intent --json preview.json
# After explicit confirmation of the returned preview:
npx flowrelay-agent endpoint-configuration-intent --json execute.json

START

USE CASES

SET UP

OPERATE

RECOVER

AGENT ACCESS

REFERENCE