> ## 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. # Send a message to the granted deployment and wait for the answer > Payman Connect resolves the grant to its one deployment, attaches that deployment's key and configuration, forwards the message, and returns what the agent said. ## OpenAPI ````yaml /api-reference/openapi.yaml post /connect/interact 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: post: tags: - Connect summary: Send a message to the granted deployment and wait for the answer description: >- Payman Connect resolves the grant to its one deployment, attaches that deployment's key and configuration, forwards the message, and returns what the agent said. operationId: connectInteract requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentInteractionRequest' responses: '200': description: The customer's agent answered headers: x-paygent-environment: schema: $ref: '#/components/schemas/ConnectEnvironment' description: Same value as the body's `environment`. content: application/json: schema: $ref: '#/components/schemas/AgentInteractionResponse' '400': $ref: '#/components/responses/BadRequest' '401': description: >- Invalid Connect credentials (`invalid_connect_credentials`) — missing, malformed, revoked, expired, or a mismatched pair. content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: >- The grant does not carry the `interact` scope (`insufficient_scope`), or a sandbox app's grant points at a non-sandbox provider (`sandbox_provider_mismatch`) — a state only reachable through data older than the environment rules. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': $ref: '#/components/responses/NotFound' '409': description: >- The deployment cannot serve this in its current state: paused (`deployment_paused` — `details.pausedReason` is `url_change` when the platform paused it over an agent URL move, null when the owner paused it themselves), or missing required configuration (`deployment_incomplete`, with `details.missingFields`). content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': $ref: '#/components/responses/TooManyRequests' '502': description: The agent rejected the call content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - connectAppKey: [] connectGrant: [] components: schemas: AgentInteractionRequest: type: object required: - userInput properties: userInput: type: string minLength: 1 sessionId: type: string nullable: true description: Reuse across turns to thread conversation history. sessionOwnerLabel: type: string nullable: true description: Display name for the end user; defaults to the caller's email. sessionAttributes: type: object additionalProperties: type: string nullable: true description: >- Extra per-call attributes merged into the ones derived from the stored configuration. Configuration wins on a key collision, so a caller cannot override a stored bank token from the request body. analysisMode: allOf: - $ref: '#/components/schemas/AnalysisMode' nullable: true ConnectEnvironment: type: string enum: - sandbox - live description: >- Which world a Connect app lives in. `sandbox` — the Durango demo bank, where nothing is money; a sandbox app may declare only DURANGO agents and its credentials are minted as `pgc_app_test_…` / `pgc_grant_test_…`. `live` — everything else; a live app cannot declare DURANGO agents. AgentInteractionResponse: type: object required: - agentId - status - message - raw - environment description: >- The common fields lifted out of the agent's answer, plus the answer itself. Agents that don't speak K2's `ExecuteAgentResponse` shape still round-trip intact through `raw`. properties: agentId: type: string environment: allOf: - $ref: '#/components/schemas/ConnectEnvironment' description: >- Which mode served this turn — assert it in your integration, so a live key in a test config (or the reverse) fails loudly at the first call instead of quietly moving the wrong kind of money. Added by this server at the route, never read off the agent's body. executionId: type: string nullable: true sessionId: type: string nullable: true status: type: string description: The agent's own status, e.g. COMPLETED or FAILED. message: type: string description: The agent's answer text; empty when the agent returned none. tokenUsage: allOf: - $ref: '#/components/schemas/TokenUsage' nullable: true approvalRef: allOf: - $ref: '#/components/schemas/ConnectApprovalRef' nullable: true description: >- The frozen operation's handle, when the run stopped for the account owner's approval. Non-null exactly when `status` is `APPROVAL_REQUIRED` — both or neither, because a ref on an otherwise ordinary turn would put an approval button in front of somebody for a payment nothing is holding. approvalExpiresAt: type: string nullable: true description: >- When that frozen operation lapses. ISO-8601 UTC. After it, the ticket is inert and replaying simply asks for approval again. approvalUrl: type: string nullable: true description: >- Payman's approval page for the frozen operation — the console origin plus the ref. raw: type: object additionalProperties: true description: The agent's response body, verbatim. 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. AnalysisMode: type: string enum: - fast - deep TokenUsage: type: object properties: inputTokens: type: integer default: 0 outputTokens: type: integer default: 0 totalTokens: type: integer default: 0 totalCost: type: number nullable: true description: USD; null when it can't be computed. ConnectApprovalRef: type: string pattern: ^pgtk_[A-Za-z0-9_-]{43}$ minLength: 48 maxLength: 48 example: pgtk_9Qv2mB7fJ0xkLpR4sTuVwXyZa1b2c3d4e5f6g7h8i9j description: >- An approval ticket's public handle: `pgtk_` and 43 characters of unpadded base64url — 32 bytes of CSPRNG, minted by the runtime and by nothing else. 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: BadRequest: description: The request failed validation content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: No such resource content: application/json: schema: $ref: '#/components/schemas/ApiError' 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`. ````