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://api.paygent.payman.ai/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": {}
}
'

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.

Body

application/json

userInput · string · required

Minimum string length: 1

sessionId · string | null

Reuse across turns to thread conversation history.

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

Response

200

application/json

The customer's agent answered

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.