Agent Tool Call

The primary gateway endpoint. Your agent calls this before performing any write action.

POST/v1/agent-tool-call

Authentication

Include the agent credential in the Authorization header:


Authorization: Bearer <agent_id>:<secret>

The credential is the secret generated when you rotate a credential in the dashboard.

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token with `agent_id:secret`
`Idempotency-Key`	Yes	Unique string for safe retries (UUID recommended)
`Content-Type`	Yes	`application/json`

The Idempotency-Key header is required. If you retry a request with the same key, Relynt returns the original response without re-executing the action.

Request body


{
  "instance_id": "run-abc-123",
  "action": "update_deal",
  "resource": "crm:deal:123",
  "payload": {
    "amount": 50000,
    "stage": "closed_won"
  }
}

Field	Type	Required	Description
`instance_id`	`string`	Yes	Per-run identifier for the agent execution
`action`	`string`	Yes	Operation string (e.g., `update_deal`, `close_ticket`)
`resource`	`string`	Yes	Target identifier (e.g., `crm:deal:123`, `ticket:INC-4451`)
`payload`	`object`	No	Action-specific data passed to the connector

Response

Allowed


{
  "decision": "allow",
  "receipt_id": "rec_abc123",
  "tool_response": {
    "status": "updated",
    "deal_id": "123"
  }
}

Denied


{
  "decision": "deny",
  "receipt_id": "rec_def456",
  "reason": "Field owner_id is not allowed to be modified"
}

Pending approval


{
  "decision": "pending_approval",
  "receipt_id": "rec_ghi789",
  "approval_id": "apr_xyz"
}

Response fields

Field	Type	Always present	Description
`decision`	`string`	Yes	`"allow"`, `"deny"`, or `"pending_approval"`
`receipt_id`	`string`	Yes	Unique receipt ID for this request
`approval_id`	`string`	No	Present when `decision` is `pending_approval`
`tool_response`	`object`	No	Connector response when `decision` is `allow`
`reason`	`string`	No	Explanation when `decision` is `deny`

Idempotency

The Idempotency-Key header ensures safe retries:

If a request with the same key has already been processed, Relynt returns the original response without re-executing the connector
Keys are scoped to the organization
Use a UUID for each unique request

Do not reuse an idempotency key for different requests. Reusing a key with different parameters will return the original response, not process the new request.

Error responses

Status	Description
`401`	Invalid or missing agent credential
`400`	Invalid request body (missing required fields)
`422`	Policy evaluation error
`500`	Internal server error

Examples

cURL


curl -X POST https://your-relynt-instance/v1/agent-tool-call \
  -H "Authorization: Bearer agent_abc123:sk_live_secret" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "run-001",
    "action": "update_deal",
    "resource": "crm:deal:42",
    "payload": {
      "amount": 75000,
      "stage": "negotiation"
    }
  }'

JavaScript


const response = await fetch(
  `${RELYNT_API_BASE_URL}/v1/agent-tool-call`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${RELYNT_AGENT_ID}:${RELYNT_AGENT_SECRET}`,
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instance_id: "run-001",
      action: "update_deal",
      resource: "crm:deal:42",
      payload: { amount: 75000, stage: "negotiation" },
    }),
  }
);
 
const result = await response.json();
 
if (result.decision === "allow") {
  console.log("Action executed:", result.tool_response);
} else if (result.decision === "deny") {
  console.log("Action denied:", result.reason);
} else if (result.decision === "pending_approval") {
  console.log("Awaiting approval:", result.approval_id);
}

Python


import requests
import uuid
 
response = requests.post(
    f"{RELYNT_API_BASE_URL}/v1/agent-tool-call",
    headers={
        "Authorization": f"Bearer {RELYNT_AGENT_ID}:{RELYNT_AGENT_SECRET}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
        "instance_id": "run-001",
        "action": "update_deal",
        "resource": "crm:deal:42",
        "payload": {"amount": 75000, "stage": "negotiation"},
    },
)
 
result = response.json()
 
match result["decision"]:
    case "allow":
        print("Action executed:", result["tool_response"])
    case "deny":
        print("Action denied:", result["reason"])
    case "pending_approval":
        print("Awaiting approval:", result["approval_id"])