Skip to main content
GET
Get card session

Authorizations

Authorization
string
header
required

Bearer authentication: send your API key, agent key, or OAuth access token as Authorization: Bearer <credential>.

Headers

X-Instance-ID
string | null

Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money.

Maximum string length: 1024

Path Parameters

sessionId
string
required

Card session ID (csn_*).

Pattern: ^csn_[0-9a-f]{32}$

Query Parameters

customerPartyId
string

Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.

Pattern: ^pty_[0-9a-f]{32}$

Response

Successful Response

sessionId
string
required
cardId
string
required
cardSource
enum<string>
required

natural_issued: an agent card Natural issued to you. external: a card the user added on the dashboard.

Available options:
natural_issued,
external
status
enum<string>
required

pending_approval: waiting for the user; keep polling. approved: claim it now. declined: the user said no. claimed: already collected. expired: open a new session.

Available options:
pending_approval,
approved,
declined,
claimed,
expired
allowedHosts
string[]
required
reference
string | null
required

The reference you created the session with. Null when you didn't set one.

purchase
object | null
required

The purchase you created the session with, as the user saw it. Null for an agent card session opened without one.

approvalExpiresAt
string
required

A pending session must be approved before this, 24 hours after creation. After it, an unapproved session is expired.

Maximum string length: 64
claimExpiresAt
string
required

An approved session must be claimed before this: approval plus claimWindowSeconds. Until the user approves, it's the latest that could be: approvalExpiresAt plus claimWindowSeconds. After it, an unclaimed session is expired.

Maximum string length: 64
claimedAt
string | null
required
Maximum string length: 64
credentialExpiresAt
string | null
required

When the claimed proxy login stops working.

Maximum string length: 64
createdAt
string
required
Maximum string length: 64
agentToken
object
required

Agent token for this purchase, when you set requestAgentToken.

note
object | null
required

Cards the user added only, once the purchase is approved: a suggestion to pass on to the user. Null when there's nothing to suggest, and always null in list results: get the session for it.