POST /v1/agent-cards/{cardId}/request

Ask to read a card. What comes back depends on the organization's mode: a one-time handle (`status: approved`) when a human has already allowed the card, or an approval link for a human to open (`status: pending_approval`). Never card details.

POST /v1/agent-cards/{cardId}/request
Ask to read a card. What comes back depends on the organization's mode: a one-time handle (`status: approved`) when a human has already allowed the card, or an approval link for a human to open (`status: pending_approval`). Never card details.

Path Parameters

cardId string required path
Card ID

Header Parameters

X-Run-ID string optional header
Workflow run recorded on the disclosure for audit

Request Body required

Request details

application/json
One of:
Option 1
Option 2
connectorId string REQUIRED
ConnectorID names the Airwallex account holding the card. Required: a request that cannot name the account produces a grant nobody can redeem. At most 255 characters, the width of the column that stores it.
purpose string
Purpose is the headline an approver reads before allowing a card to be read, and the only field shown on that decision — bounded so an agent cannot fill the surface it is judged on.

Responses

200 OK
application/json
code integer
data object
approvalUrl string
cardId string
expiresAt string
handle string
requestId string
status string
message string
requestId string
400 Bad Request
403 Forbidden 
curl -X POST 'https://api.example.com/v1/agent-cards/string/request' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{}'
const response = await fetch('https://api.example.com/v1/agent-cards/string/request', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({})});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://api.example.com/v1/agent-cards/string/request', headers=headers, json={})print(response.json())
package mainimport (	"fmt"	"io"	"net/http"	"strings")func main() {	body := strings.NewReader(`{}`)	req, _ := http.NewRequest("POST", "https://api.example.com/v1/agent-cards/string/request", body)	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")	req.Header.Set("Content-Type", "application/json")	resp, _ := http.DefaultClient.Do(req)	defer resp.Body.Close()	result, _ := io.ReadAll(resp.Body)	fmt.Println(string(result))}
200 Response 
{  "code": 200,  "data": {    "approvalUrl": "<string>",    "cardId": "<string>",    "expiresAt": "<string>",    "handle": "<string>",    "requestId": "<string>",    "status": "<string>"  },  "message": "success",  "requestId": "abc-123"}
Previous POST /v1/agent-cards/{cardId}/disclosure
Next GET /v1/ai/pulse