---
title: "Submit field values and an action for the current step"
method: POST
path: "/flow/sessions/{sessionId}/steps/{stepId}"
tags: ["Flow Sessions"]
---

# Submit field values and an action for the current step

`POST /flow/sessions/{sessionId}/steps/{stepId}`

Advances the session by submitting user input. Requires an `Idempotency-Key`
header (max 256 chars) to prevent duplicate processing. `stateVersion` provides
optimistic concurrency control — must match the current version.

If the step declares a `payment` field, the `X-Payment` header must contain a
base64-encoded x402 Permit2 payment proof. On successful settlement the response
includes `paymentReceipt` and a `X-Payment-Response` header.

## Path parameters

- `sessionId` string, required
- `stepId` string, required

## Headers

- `Idempotency-Key` string, required
- `X-Payment` string

## Request body

- object
  - `fieldValues` object, required — Key–value map of field IDs to submitted values
  - `action` string, required — Action ID from the StepSpec's `actions` array
  - `stateVersion` integer, required — Must match the current session state version (optimistic lock)

## Response `200`

Step submitted — returns next step or completion

- SessionResponse
  - `sessionId` string, required
  - `appId` string, required
  - `appVersion` string, required
  - `status` 'active' | 'complete' | 'expired', required
  - `stepSpec` StepSpec, required
    - `id` string, required
    - `screen` ScreenSpec, required
      - `template` 'form' | 'review' | 'info' | 'document', required
      - `title` string
      - `description` string
      - `icon` string
    - `fields` StepField[], required
      - `id` string, required
      - `type` 'text-input' | 'text-area' | 'number' | 'currency' | 'select' | 'checkbox' | 'date' | 'radio-group' | 'display' | 'table' | 'wallet', required
      - `label` string
      - `placeholder` string
      - `required` boolean
      - `defaultValue` unknown
      - `minLength` integer
      - `maxLength` integer
      - `pattern` string
      - `rows` integer
      - `min` union
        - number
        - string
      - `max` union
        - number
        - string
      - `step` number
      - `currencyCode` string
      - `options` SelectOption[]
        - `value` string, required
        - `label` string, required
      - `defaultChecked` boolean
      - `value` unknown
      - `format` 'text' | 'currency' | 'date' | 'percentage'
      - `dataRef` string
      - `submitResolve` string — For `select` / `radio-group` fields whose options are sourced from `$appState`. On submit, Overledger replaces the chosen option's `value` with the full underlying record from app state before invoking the step handler. Format mirrors `dataRef` (e.g. `"$appState.connections"`); the handler receives the object at that path keyed by the selected option, not just the option id.
      - `columns` TableColumn[]
        - `key` string, required
        - `label` string, required
        - `format` 'text' | 'currency' | 'date' | 'percentage'
      - `rowsData` object[]
      - `emptyMessage` string
      - `limit` integer
      - `pageSize` integer
      - `config` WalletConfig
        - `action` string, required
        - `chains` string[]
        - `message` string
        - `transaction` object
    - `actions` StepAction[], required
      - `id` string, required
      - `type` 'submit', required
      - `label` string, required
      - `style` 'primary' | 'secondary' | 'danger'
      - `disabled` boolean
      - `confirmationMessage` string
    - `message` union
      - string
      - StepMessage
        - `text` string, required
        - `type` 'info' | 'warning' | 'error' | 'success'
    - `errors` BusinessValidationError[]
      - `fieldId` string, required
      - `code` string
      - `message` string, required
    - `agent` AgentMeta
      - `hint` string — LLM-optimised description of this step's purpose
      - `emits` string[] — Webhook event type IDs this step may emit
      - `riskLevel` 'safe' | 'caution' | 'irreversible'
      - `outputQuery` string — Query ID to read the resulting state after this step
      - `idempotent` boolean — Whether this step is safe to retry without side-effects
    - `payment` StepPayment
      - `amountAtomicUnits` string, required — Positive integer string in smallest denomination (e.g. "5000000" for 5 USDC)
      - `currency` string, required
      - `chain` string, required
      - `recipient` string, required
      - `description` string
      - `actions` string[] — Action IDs that require payment. Defaults to all submit actions.
      - `tokenAddress` string
    - `entryPoint` boolean — Set by Overledger when this step is a declared session entry point
  - `stateVersion` integer, required
  - `complete` boolean, required
  - `_links` HypermediaLinks, required
    - `self` string
    - `submit` string
  - `paymentReceipt` X402SettlementReceipt
    - `txHash` string, required
    - `chainId` integer, required
    - `blockNumber` integer, required
    - `settledAt` string, date-time, required

## Other responses

- `400` — Bad request (RFC 7807)
- `401` — Unauthorized (RFC 7807)
- `402` — Payment required (x402)
- `404` — Not found (RFC 7807)
- `409` — Conflict — state version mismatch or idempotency key collision (RFC 7807)
- `410` — Session expired or already complete (RFC 7807)
- `429` — Rate limit exceeded (RFC 7807)
- `502` — Flow App error, payment settlement failure, or content filter violation (RFC 7807)

---

[API](https://skmtc.net/overledger/apis/overledger-server.md) · [All operations](https://skmtc.net/overledger/apis/overledger-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/overledger/overledger-server/versions/dd31e0a52064/schema)