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.

POST /connect/interact

Send a message to the granted deployment and wait for the answer

cURL

curl --request POST \
  --url https://paygent-cloud-server-production.up.railway.app/connect/interact \
  --header 'Content-Type: application/json' \
  --header 'x-paygent-connect-app-key: <api-key>' \
  --header 'x-paygent-connect-grant: <api-key>' \
  --data '
{
  "userInput": "<string>",
  "sessionId": "<string>",
  "sessionOwnerLabel": "<string>",
  "sessionAttributes": {},
  "provider": "<string>"
}
'

200

{
  "agentId": "<string>",
  "environment": "sandbox",
  "status": "<string>",
  "message": "<string>",
  "raw": {},
  "executionId": "<string>",
  "sessionId": "<string>",
  "tokenUsage": {
    "inputTokens": 0,
    "outputTokens": 0,
    "totalTokens": 0,
    "totalCost": 123
  },
  "approvalRef": "pgtk_9Qv2mB7fJ0xkLpR4sTuVwXyZa1b2c3d4e5f6g7h8i9j",
  "approvalExpiresAt": "<string>",
  "approvalUrl": "<string>"
}

Authorizations

x-paygent-connect-app-key · string · header · required

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.

x-paygent-connect-grant · string · header · required

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.

Headers

Idempotency-Key · string

A key of your own choosing that names ONE instruction, so a retry of it is not a second execution. Scoped to your grant, so it cannot collide with another app's.

Required string length: 16 - 255

Pattern: ^[A-Za-z0-9._~-]+$

Body

application/json

userInput · string · required

Minimum string length: 1

sessionId · string | null

Reuse within one conversation to thread history. On Connect, also scopes short-lived explicit account selection for referential follow-ups; use a new ID for each chat.

sessionOwnerLabel · string | null

Display name for the end user; defaults to the caller's email.

sessionAttributes · object | null

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.

Show child attributes

analysisMode · enum<string> | null

Available options: fast, deep

provider · string | null

Which connected account a multi-provider wallet should use — an institution type (BREX) or an account label, exactly as a needs_provider result's candidates listed them. Optional.

Maximum string length: 256

Response

200

application/json

The customer's agent answered — or, on a multi-provider grant, the router answered instead of dispatching: a body whose status is needs_provider or no_capable_provider (see ConnectRoutingDecision) means no agent ran, nothing was charged, and the app should re-ask per howToProceed rather than retry.

Option 1

Option 2

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.

agentId · string · required

environment · enum<string> · required

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.

Available options: sandbox, live

status · string · required

The agent's own status, e.g. COMPLETED or FAILED.

message · string · required

The agent's answer text; empty when the agent returned none.

raw · object · required

The agent's response body, verbatim.

executionId · string | null

sessionId · string | null

tokenUsage · object | null

Show child attributes

approvalRef · string | null

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.

Required string length: 48

Pattern: ^pgtk_[A-Za-z0-9_-]{43}$

Example:

"pgtk_9Qv2mB7fJ0xkLpR4sTuVwXyZa1b2c3d4e5f6g7h8i9j"

approvalExpiresAt · string | null

When that frozen operation lapses. ISO-8601 UTC. After it, the ticket is inert and replaying simply asks for approval again.

approvalUrl · string | null

Payman's approval page for the frozen operation — the console origin plus the ref.