Quant Network Flow Sessions API

openapi: 3.2.0
info:
  title: Overledger Server Flow Sessions API
  description: The Overledger Server is the primary client-facing gateway.
  version: 1.0.0
servers:
- url: https://fusion-rollup.quant.dev
  description: Testnet (live) — the public Fusion Server endpoint
- url: http://localhost:8080
  description: Local development
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Flow Sessions
  description: Multi-step Flow App session management
paths:
  /flow/sessions:
    post:
      tags:
      - Flow Sessions
      operationId: createSession
      summary: Create a new Flow App session
      description: 'Starts a new session for the specified Flow App. Optionally target a specific

        app version and/or a declared start step (multi-start-step apps).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - appId
              properties:
                appId:
                  type: string
                  minLength: 1
                  description: ID of the Flow App to instantiate
                version:
                  type: string
                  minLength: 1
                  description: Semver version. Defaults to latest active version.
                launchContext:
                  type: object
                  additionalProperties: true
                  description: Arbitrary context passed to the app's start step render
                startStepId:
                  type: string
                  minLength: 1
                  maxLength: 100
                  pattern: ^[a-zA-Z0-9_-]+$
                  description: 'Entry point step ID. Must be a declared start step when the app declares any. Defaults to the app''s first declared start step.

                    '
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '400':
          $ref: '#/components/responses/FlowBadRequest'
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '404':
          $ref: '#/components/responses/FlowNotFound'
        '422':
          description: Unprocessable — incompatible SDK version
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          $ref: '#/components/responses/FlowTooManyRequests'
        '502':
          $ref: '#/components/responses/FlowBadGateway'
    get:
      tags:
      - Flow Sessions
      operationId: listSessions
      summary: List sessions for the authenticated client
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        schema:
          type: string
        description: Opaque cursor from a previous response's `pagination.nextCursor`
      - name: appId
        in: query
        schema:
          type: string
        description: Filter by Flow App ID
      - name: status
        in: query
        schema:
          $ref: '#/components/schemas/SessionStatus'
        description: Filter by session status
      responses:
        '200':
          description: Paginated session list
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SessionListItem'
                  pagination:
                    $ref: '#/components/schemas/FlowPaginationMeta'
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '429':
          $ref: '#/components/responses/FlowTooManyRequests'
  /flow/sessions/{sessionId}:
    get:
      tags:
      - Flow Sessions
      operationId: getSession
      summary: Get session metadata
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Session metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListItem'
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '404':
          $ref: '#/components/responses/FlowNotFound'
        '410':
          $ref: '#/components/responses/FlowGone'
  /flow/sessions/{sessionId}/steps/{stepId}:
    get:
      tags:
      - Flow Sessions
      operationId: getStep
      summary: Get the current step's StepSpec
      description: 'Returns the cached StepSpec for the current step. The `stepId` must match

        the session''s current step — returns 404 otherwise.'
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: stepId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Current step
          content:
            application/json:
              schema:
                type: object
                required:
                - stepSpec
                - stateVersion
                - complete
                - _links
                properties:
                  stepSpec:
                    $ref: '#/components/schemas/StepSpec'
                  stateVersion:
                    type: integer
                    minimum: 1
                  complete:
                    type: boolean
                  _links:
                    $ref: '#/components/schemas/HypermediaLinks'
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '404':
          $ref: '#/components/responses/FlowNotFound'
        '410':
          $ref: '#/components/responses/FlowGone'
    post:
      tags:
      - Flow Sessions
      operationId: submitStep
      summary: Submit field values and an action for the current step
      description: '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.'
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: stepId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
        description: Unique key for idempotent submission. Cached per session.
      - name: X-Payment
        in: header
        schema:
          type: string
        description: Base64-encoded x402 Permit2 payment proof (required when step has `payment`)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - fieldValues
              - action
              - stateVersion
              properties:
                fieldValues:
                  type: object
                  additionalProperties: true
                  description: Key–value map of field IDs to submitted values
                action:
                  type: string
                  minLength: 1
                  description: Action ID from the StepSpec's `actions` array
                stateVersion:
                  type: integer
                  minimum: 1
                  description: Must match the current session state version (optimistic lock)
      responses:
        '200':
          description: Step submitted — returns next step or completion
          headers:
            X-Payment-Response:
              description: Base64-encoded JSON of X402SettlementReceipt (present when payment settled)
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '400':
          $ref: '#/components/responses/FlowBadRequest'
        '401':
          $ref: '#/components/responses/FlowUnauthorized'
        '402':
          $ref: '#/components/responses/FlowPaymentRequired'
        '404':
          $ref: '#/components/responses/FlowNotFound'
        '409':
          $ref: '#/components/responses/FlowConflict'
        '410':
          $ref: '#/components/responses/FlowGone'
        '429':
          $ref: '#/components/responses/FlowTooManyRequests'
        '502':
          $ref: '#/components/responses/FlowBadGateway'
components:
  schemas:
    SessionListItem:
      type: object
      required:
      - sessionId
      - appId
      - appVersion
      - status
      - currentStepId
      - createdAt
      - updatedAt
      properties:
        sessionId:
          type: string
        appId:
          type: string
        appVersion:
          type: string
        status:
          $ref: '#/components/schemas/SessionStatus'
        currentStepId:
          type: string
        startStepId:
          type: string
          description: The step this session started on (absent for pre-multi-start sessions)
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    RiskLevel:
      type: string
      enum:
      - safe
      - caution
      - irreversible
    TemplateType:
      type: string
      enum:
      - form
      - review
      - info
      - document
    DisplayFormat:
      type: string
      enum:
      - text
      - currency
      - date
      - percentage
    WalletConfig:
      type: object
      required:
      - action
      properties:
        action:
          type: string
        chains:
          type: array
          items:
            type: string
        message:
          type: string
        transaction:
          type: object
          additionalProperties: true
    BusinessValidationError:
      type: object
      required:
      - fieldId
      - message
      properties:
        fieldId:
          type: string
        code:
          type: string
        message:
          type: string
    ProblemDetails:
      type: object
      description: RFC 7807 Problem Details — used by all /flow/* endpoints
      required:
      - type
      - title
      - status
      - detail
      - retryable
      properties:
        type:
          type: string
          description: Error classification URI
          example: urn:fusion:error:bad-request
        title:
          type: string
          example: Bad Request
        status:
          type: integer
          example: 400
        detail:
          type: string
          example: appId is required
        retryable:
          type: boolean
          description: Whether the client should retry this request
        instance:
          type: string
          description: Request ID for correlation
    X402Descriptor:
      type: object
      required:
      - version
      - scheme
      - networkId
      - amountAtomicUnits
      - currency
      - recipient
      properties:
        version:
          type: string
          enum:
          - '1'
        scheme:
          type: string
          enum:
          - evm
        networkId:
          type: string
        amountAtomicUnits:
          type: string
        currency:
          type: string
        recipient:
          type: string
        description:
          type: string
        tokenAddress:
          type: string
        permit2Address:
          type: string
        spender:
          type: string
          description: Settlement wallet address (server spender)
    X402SettlementReceipt:
      type: object
      required:
      - txHash
      - chainId
      - blockNumber
      - settledAt
      properties:
        txHash:
          type: string
        chainId:
          type: integer
        blockNumber:
          type: integer
        settledAt:
          type: string
          format: date-time
    ScreenSpec:
      type: object
      required:
      - template
      properties:
        template:
          $ref: '#/components/schemas/TemplateType'
        title:
          type: string
        description:
          type: string
        icon:
          type: string
    StepPayment:
      type: object
      required:
      - amountAtomicUnits
      - currency
      - chain
      - recipient
      properties:
        amountAtomicUnits:
          type: string
          pattern: ^\d+$
          description: Positive integer string in smallest denomination (e.g. "5000000" for 5 USDC)
        currency:
          type: string
          example: USDC
        chain:
          type: string
          example: base
        recipient:
          $ref: '#/components/schemas/EvmAddress'
        description:
          type: string
        actions:
          type: array
          items:
            type: string
          description: Action IDs that require payment. Defaults to all submit actions.
        tokenAddress:
          $ref: '#/components/schemas/EvmAddress'
    ActionType:
      type: string
      enum:
      - submit
    SelectOption:
      type: object
      required:
      - value
      - label
      properties:
        value:
          type: string
        label:
          type: string
    EvmAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      example: '0xAbCd1234AbCd1234AbCd1234AbCd1234AbCd1234'
    StepAction:
      type: object
      required:
      - id
      - type
      - label
      properties:
        id:
          type: string
          minLength: 1
        type:
          $ref: '#/components/schemas/ActionType'
        label:
          type: string
          minLength: 1
        style:
          $ref: '#/components/schemas/ActionStyle'
        disabled:
          type: boolean
        confirmationMessage:
          type: string
    SessionResponse:
      type: object
      required:
      - sessionId
      - appId
      - appVersion
      - status
      - stepSpec
      - stateVersion
      - complete
      - _links
      properties:
        sessionId:
          type: string
        appId:
          type: string
        appVersion:
          type: string
        status:
          $ref: '#/components/schemas/SessionStatus'
        stepSpec:
          $ref: '#/components/schemas/StepSpec'
        stateVersion:
          type: integer
          minimum: 1
        complete:
          type: boolean
        _links:
          $ref: '#/components/schemas/HypermediaLinks'
        paymentReceipt:
          $ref: '#/components/schemas/X402SettlementReceipt'
          description: Present only when x402 Permit2 payment was settled during submit
    StepMessage:
      type: object
      required:
      - text
      properties:
        text:
          type: string
        type:
          type: string
          enum:
          - info
          - warning
          - error
          - success
    StepField:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          minLength: 1
        type:
          $ref: '#/components/schemas/FieldType'
        label:
          type: string
        placeholder:
          type: string
        required:
          type: boolean
        defaultValue: {}
        minLength:
          type: integer
          minimum: 0
        maxLength:
          type: integer
          minimum: 1
        pattern:
          type: string
        rows:
          type: integer
          minimum: 1
        min:
          oneOf:
          - type: number
          - type: string
        max:
          oneOf:
          - type: number
          - type: string
        step:
          type: number
        currencyCode:
          type: string
        options:
          type: array
          items:
            $ref: '#/components/schemas/SelectOption'
        defaultChecked:
          type: boolean
        value: {}
        format:
          $ref: '#/components/schemas/DisplayFormat'
        dataRef:
          type: string
        submitResolve:
          type: string
          description: '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:
          type: array
          items:
            $ref: '#/components/schemas/TableColumn'
        rowsData:
          type: array
          items:
            type: object
            additionalProperties: true
        emptyMessage:
          type: string
        limit:
          type: integer
          minimum: 1
        pageSize:
          type: integer
          minimum: 1
        config:
          $ref: '#/components/schemas/WalletConfig'
      description: 'Field schema is polymorphic on `type`. Not all properties apply to every type:

        - text-input / text-area: placeholder, required, minLength, maxLength, pattern, rows (text-area only)

        - number / currency: required, min, max, step, currencyCode (currency only)

        - select / radio-group: required, options, dataRef, submitResolve, limit

        - checkbox: required, defaultChecked

        - date: required, min (ISO date string), max (ISO date string)

        - display: value, format, dataRef

        - table: columns (required), rowsData, emptyMessage, dataRef, limit, pageSize

        - wallet: config (required)

        '
    HypermediaLinks:
      type: object
      properties:
        self:
          type: string
        submit:
          type: string
    FlowPaginationMeta:
      type: object
      required:
      - hasMore
      - totalCount
      properties:
        nextCursor:
          type: string
        hasMore:
          type: boolean
        totalCount:
          type: integer
    ActionStyle:
      type: string
      enum:
      - primary
      - secondary
      - danger
    SessionStatus:
      type: string
      enum:
      - active
      - complete
      - expired
    StepSpec:
      type: object
      required:
      - id
      - screen
      - fields
      - actions
      properties:
        id:
          type: string
          minLength: 1
        screen:
          $ref: '#/components/schemas/ScreenSpec'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/StepField'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/StepAction'
        message:
          oneOf:
          - type: string
          - $ref: '#/components/schemas/StepMessage'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BusinessValidationError'
        agent:
          $ref: '#/components/schemas/AgentMeta'
        payment:
          $ref: '#/components/schemas/StepPayment'
        entryPoint:
          type: boolean
          description: Set by Overledger when this step is a declared session entry point
    TableColumn:
      type: object
      required:
      - key
      - label
      properties:
        key:
          type: string
        label:
          type: string
        format:
          $ref: '#/components/schemas/DisplayFormat'
    FieldType:
      type: string
      enum:
      - text-input
      - text-area
      - number
      - currency
      - select
      - checkbox
      - date
      - radio-group
      - display
      - table
      - wallet
    AgentMeta:
      type: object
      properties:
        hint:
          type: string
          description: LLM-optimised description of this step's purpose
        emits:
          type: array
          items:
            type: string
          description: Webhook event type IDs this step may emit
        riskLevel:
          $ref: '#/components/schemas/RiskLevel'
        outputQuery:
          type: string
          description: Query ID to read the resulting state after this step
        idempotent:
          type: boolean
          description: Whether this step is safe to retry without side-effects
  responses:
    FlowNotFound:
      description: Not found (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:not-found
            title: Not Found
            status: 404
            detail: Session not found
            retryable: false
    FlowConflict:
      description: Conflict — state version mismatch or idempotency key collision (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:conflict
            title: Conflict
            status: 409
            detail: State version mismatch — expected 2, got 1
            retryable: true
    FlowPaymentRequired:
      description: Payment required (x402)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/X402Descriptor'
      headers:
        X-Payment-Required:
          description: Base64-encoded JSON of the X402Descriptor
          schema:
            type: string
    FlowTooManyRequests:
      description: Rate limit exceeded (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:too-many-requests
            title: Too Many Requests
            status: 429
            detail: Rate limit exceeded
            retryable: true
    FlowBadRequest:
      description: Bad request (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:bad-request
            title: Bad Request
            status: 400
            detail: appId is required
            retryable: false
    FlowBadGateway:
      description: Flow App error, payment settlement failure, or content filter violation (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:bad-gateway
            title: Bad Gateway
            status: 502
            detail: Flow App returned invalid response
            retryable: true
    FlowUnauthorized:
      description: Unauthorized (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:unauthorized
            title: Unauthorized
            status: 401
            detail: Invalid client credentials
            retryable: false
    FlowGone:
      description: Session expired or already complete (RFC 7807)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:fusion:error:gone
            title: Gone
            status: 410
            detail: Session has expired
            retryable: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'A Keycloak access token (JWT), verified against the realm JWKS

        (signature / issuer / expiry). The caller''s identity is the token''s

        `sub` claim — this is **not** a `clientId`.

        '
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'An Overledger-issued API key of the form `fk_<keyId>.<secret>`, minted via

        `POST /users/me/api-keys`. Accepted on any route and **takes precedence**

        over the `Authorization` header when both are supplied. Resolves to the

        same identity (Keycloak `sub`) as the equivalent Bearer JWT.

        '
x-provenance:
  method: searched
  source: https://docs.overledger.dev/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.overledger.dev/reference/checkdepositstatus.md
  - https://docs.overledger.dev/reference/checkswapstatus.md
  - https://docs.overledger.dev/reference/checkwithdrawalstatus.md
  - https://docs.overledger.dev/reference/createdeposit.md
  - https://docs.overledger.dev/reference/createsession.md
  - https://docs.overledger.dev/reference/createsubscription.md
  - https://docs.overledger.dev/reference/createswap.md
  - https://docs.overledger.dev/reference/createwithdrawal.md
  - https://docs.overledger.dev/reference/delete_deployed-contracts-contractaddress-permissions.md
  - https://docs.overledger.dev/reference/delete_nodes-nodeid.md
  - https://docs.overledger.dev/reference/deletesubscription.md
  - https://docs.overledger.dev/reference/get_deployed-contracts-contractaddress-permissions.md
  - https://docs.overledger.dev/reference/get_deployed-contracts-contractaddress.md
  - https://docs.overledger.dev/reference/get_health.md
  - https://docs.overledger.dev/reference/get_metrics.md
  - https://docs.overledger.dev/reference/get_networks-fusion.md
  - https://docs.overledger.dev/reference/get_networks-total.md
  - https://docs.overledger.dev/reference/get_networks.md
  - https://docs.overledger.dev/reference/get_ready.md
  - https://docs.overledger.dev/reference/get_stakes-address.md
  - https://docs.overledger.dev/reference/get_users-me-access-details.md
  - https://docs.overledger.dev/reference/get_users-me-deployed-contracts.md
  - https://docs.overledger.dev/reference/get_users-me-id.md
  - https://docs.overledger.dev/reference/get_users-me-nodes.md
  - https://docs.overledger.dev/reference/get_users-me-providers.md
  - https://docs.overledger.dev/reference/get_users-me-stakes-total.md
  - https://docs.overledger.dev/reference/get_users-me-stakes.md
  - https://docs.overledger.dev/reference/get_users-me-transactions.md
  - https://docs.overledger.dev/reference/getactionablewithdrawals.md
  - https://docs.overledger.dev/reference/getallowedcomponents.md
  - https://docs.overledger.dev/reference/getapp.md
  - https://docs.overledger.dev/reference/getdeposit.md
  - https://docs.overledger.dev/reference/getdepositallowance.md
  - https://docs.overledger.dev/reference/getdepositbalances.md
  - https://docs.overledger.dev/reference/getsession.md
  - https://docs.overledger.dev/reference/getstep.md
  - https://docs.overledger.dev/reference/getsupportedswaptokens.md
  - https://docs.overledger.dev/reference/getswap.md
  - https://docs.overledger.dev/reference/getswapquote.md
  - https://docs.overledger.dev/reference/gettransactionstatus.md
  - https://docs.overledger.dev/reference/getuserhistory.md
  - https://docs.overledger.dev/reference/getuserswaps.md
  - https://docs.overledger.dev/reference/getuserwithdrawals.md
  - https://docs.overledger.dev/reference/getwithdrawalbyid.md
  - https://docs.overledger.dev/reference/listaddressevents.md
  - https://docs.overledger.dev/reference/listapikeys.md
  - https://docs.overledger.dev/reference/listapps.md
  - https://docs.overledger.dev/reference/listeventsubscriptionevents.md
  - https://docs.overledger.dev/reference/listsessions.md
  - https://docs.overledger.dev/reference/listsubscriptions.md
  - https://docs.overledger.dev/reference/listuserdeposits.md
  - https://docs.overledger.dev/reference/mintapikey.md
  - https://docs.overledger.dev/reference/post_deployed-contracts-contractaddress-permissions.md
  - https://docs.overledger.dev/reference/post_nodes.md
  - https://docs.overledger.dev/reference/post_rpc-apikey.md
  - https://docs.overledger.dev/reference/post_stakes.md
  - https://docs.overledger.dev/reference/post_users-me-providers-providerid-reactivate.md
  - https://docs.overledger.dev/reference/put_deployed-contracts-contractaddress.md
  - https://docs.overledger.dev/reference/put_users-me-providers-providerid-reset-policy.md
  - https://docs.overledger.dev/reference/queryappstate.md
  - https://docs.overledger.dev/reference/recordfinalizetx.md
  - https://docs.overledger.dev/reference/recordprovetx.md
  - https://docs.overledger.dev/reference/replayevents.md
  - https://docs.overledger.dev/reference/revokeapikey.md
  - https://docs.overledger.dev/reference/submitstep.md
  - https://docs.overledger.dev/reference/subscribeaddress.md
  - https://docs.overledger.dev/reference/subscribeevent.md
  - https://docs.overledger.dev/reference/tracktransaction.md
  - https://docs.overledger.dev/reference/unsubscribeaddress.md
  - https://docs.overledger.dev/reference/unsubscribeevent.md
  merge:
    pages: 70
    deduped: 480
    conflicts_kept_first: 0