> ## Documentation Index
> Fetch the complete documentation index at: https://paymanai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Answer a run that stopped to ask something

> A money tool can stop a run to ask a question — which recipient, confirm this transfer — and the run blocks until it is answered. The answer goes back over the runtime's api-key surface, which the caller must never hold, so it is proxied here. No deployment segment in the path: the grant names the deployment.



## OpenAPI

````yaml /api-reference/openapi.yaml post /connect/interact/user-action/{userActionId}/{action}
openapi: 3.0.3
info:
  title: Payman Connect API
  version: 0.1.0
  description: >-
    The HTTP contract behind Payman Connect: exchange a customer's consent for a
    grant, send actions against the accounts it reaches, and follow an approval
    to its receipt. Every call carries your app key, and every call after the
    exchange carries the grant. Non-2xx responses share one `ApiError` envelope.
    Most integrations never write these calls: the SDK speaks them for you.
servers:
  - url: https://api.paygent.payman.ai
    description: Production
  - url: http://localhost:8891
    description: A local stack
security:
  - bearerAuth: []
tags:
  - name: Connect
    description: >-
      Third-party access. A registered app presents its app key together with a
      grant token its customer consented to; the pair reaches exactly the one
      deployment the grant names, and nothing else on this API.
paths:
  /connect/interact/user-action/{userActionId}/{action}:
    parameters:
      - name: userActionId
        in: path
        required: true
        schema:
          type: string
          maxLength: 256
        description: The runtime's id for the pending action. Opaque to this server.
      - name: action
        in: path
        required: true
        schema:
          type: string
          enum:
            - submit
            - cancel
            - expired
            - resend
    post:
      tags:
        - Connect
      summary: Answer a run that stopped to ask something
      description: >-
        A money tool can stop a run to ask a question — which recipient, confirm
        this transfer — and the run blocks until it is answered. The answer goes
        back over the runtime's api-key surface, which the caller must never
        hold, so it is proxied here. No deployment segment in the path: the
        grant names the deployment.
      operationId: connectAnswerUserAction
      requestBody:
        required: false
        description: The answer, for `submit`. Ignored by the other three.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The runtime accepted it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserActionAck'
        '401':
          description: Invalid Connect credentials (`invalid_connect_credentials`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: The grant does not carry the `interact` scope (`insufficient_scope`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: >-
            Gone, already answered, or never raised on this grant's streams —
            one status for all three, so ids cannot be probed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - connectAppKey: []
          connectGrant: []
components:
  schemas:
    UserActionAck:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
    ApiError:
      type: object
      required:
        - category
        - code
        - message
      description: >-
        The envelope every non-2xx response uses. `code` is a stable slug a
        client can match on exactly; `message` is safe to show a user as-is.
      properties:
        category:
          $ref: '#/components/schemas/ApiErrorCategory'
        code:
          type: string
          example: agent_not_configured
        message:
          type: string
          example: Configure this agent before sending it messages.
        details:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Structured context — field errors, the agent's own status, and so
            on.
    ApiErrorCategory:
      type: string
      description: >-
        Fixed taxonomy, matching K2's so a client that already handles K2 errors
        handles these too.
      enum:
        - VALIDATION
        - AUTH
        - PERMISSION
        - NOT_FOUND
        - CONFLICT
        - RATE_LIMIT
        - UPSTREAM
        - TIMEOUT
        - INTERNAL
  responses:
    TooManyRequests:
      description: >-
        Rate limited (`rate_limited`). `details` carries the limit, the window
        and how long until it reopens.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    connectAppKey:
      type: apiKey
      in: header
      name: x-paygent-connect-app-key
      description: >-
        A Connect app key (`pgc_app_…`), identifying the registered third-party
        app. Always presented together with `connectGrant` — the pair is one
        credential, and either half alone is refused. Accepted on the
        `/connect/*` surface only.
    connectGrant:
      type: apiKey
      in: header
      name: x-paygent-connect-grant
      description: >-
        A Connect grant token (`pgc_grant_…`): one user's consent for the
        presenting app to reach one deployment. Every failure mode — missing,
        malformed, revoked, expired, or paired with the wrong app key — answers
        the same 401 `invalid_connect_credentials`.

````