Update agent policy

Partially update an agent’s policy. Only provided fields will be updated; omitted fields retain their current values. Policy changes take effect immediately. The spending limits currency is immutable; attempting to change it returns a 400 response.

PATCH /agents/{agentId}/policy

Update agent policy

cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/policy \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "permissions": [],
  "spendingLimits": {
    "currency": "USD",
    "perTransactionLimit": 50000,
    "dailyLimit": 500000,
    "dailyTransactionLimit": 10,
    "monthlyLimit": 5000000
  },
  "accountRestrictions": {
    "allowedAccountIds": [
      "Account:019542f5-b3e7-1d02-0000-000000000001"
    ],
    "accountRules": [
      {
        "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
        "perTransactionLimit": 10000
      }
    ]
  },
  "approvalThresholds": {
    "currency": "USD",
    "amount": 100000
  }
}
'

200

{
  "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
  "name": "Payroll Automation Agent",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "isPaused": false,
  "isConnected": true,
  "policy": {
    "permissions": [
      "VIEW_TRANSACTIONS"
    ],
    "defaultExecutionMode": "AUTO",
    "spendingLimits": {
      "currency": "USD",
      "perTransactionLimit": 50000,
      "dailyLimit": 500000,
      "dailyTransactionLimit": 10,
      "monthlyLimit": 5000000
    },
    "accountRestrictions": {
      "allowedAccountIds": [
        "Account:019542f5-b3e7-1d02-0000-000000000001"
      ],
      "accountRules": [
        {
          "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
          "executionMode": "AUTO",
          "perTransactionLimit": 10000
        }
      ]
    },
    "approvalThresholds": {
      "currency": "USD",
      "amount": 100000
    }
  },
  "usage": {
    "dailyTransactionCount": 3,
    "dailySpend": 150000,
    "monthlySpend": 750000,
    "dailyResetDate": "2025-07-22",
    "monthlyResetMonth": "2025-08"
  },
  "createdAt": "2025-07-21T17:32:28Z",
  "updatedAt": "2025-07-21T17:32:28Z",
  "actingFor": "member_8f2c1a",
  "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Path Parameters

agentId · string · required

System-generated unique agent identifier

Body

application/json

Partial update to an agent's policy. Only provided fields will be updated; omitted fields retain their current values.

permissions · enum<string>[]

Updated list of permissions. Replaces the entire permissions list when provided.

Permission granted to an agent that determines what actions it can perform. VIEW_TRANSACTIONS: Can list and retrieve transactions and account balances. CREATE_QUOTES: Can create quotes. EXECUTE_QUOTES: Can execute quotes. MANAGE_EXTERNAL_ACCOUNTS: Can create and manage external accounts. RECEIVE_FUNDS: Can create deposit targets for receiving funds. MANAGE_IDENTITY: Can read and update customer identity information and start verification. MANAGE_CARDS: Can read, tighten, and freeze its cards. ISSUE_CARDS: Can issue one standard virtual card for itself while it holds no live standard card, and single-use and recurring purchase cards where the platform enables them. USE_STORED_CARDS: Can list the customer's stored cards it is allowed to use and ask for a single-use link to one's details. Never granted by default. MANAGE_SETTLEMENT_RULES: Can propose settlement rules that split the customer's incoming payments into its Embedded Wallet, read and delete the rules it created, and cancel their held executions.

Available options: VIEW_TRANSACTIONS, CREATE_QUOTES, EXECUTE_QUOTES, MANAGE_EXTERNAL_ACCOUNTS, RECEIVE_FUNDS, MANAGE_IDENTITY, MANAGE_CARDS, ISSUE_CARDS, USE_STORED_CARDS, MANAGE_SETTLEMENT_RULES

defaultExecutionMode · enum<string>

Execution mode controlling whether agent actions require human approval. AUTO: The agent can execute actions autonomously without explicit approval. APPROVAL_REQUIRED: All agent actions require explicit human approval before execution.

Available options: AUTO, APPROVAL_REQUIRED

spendingLimits · object

Partial update to spending limits. Only provided fields will be updated; omitted fields retain their current values.

Show child attributes

accountRestrictions · object

Optional restrictions that limit the agent to specific accounts or override policy per account.

Show child attributes

approvalThresholds · object

Thresholds that force approval for high-value transactions, overriding the default execution mode. The threshold currency must equal the policy's spending limits currency. When a transaction is denominated in a different currency, Grid converts it to the policy currency at evaluation time.

Show child attributes

Response

200

application/json

Agent policy updated successfully

A programmatic agent with scoped permissions and a spending policy, used to automate payment workflows.

id · string · required

System-generated unique identifier for the agent.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000001"

name · string · required

Human-readable name for the agent.

Example:

"Payroll Automation Agent"

customerId · string · required

The ID of the customer this agent operates on behalf of.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

isPaused · boolean · required

Whether the agent is currently paused. Paused agents cannot initiate any actions.

Example:

false

isConnected · boolean · required

Whether the agent has been installed and connected (i.e., its device code has been redeemed).

Example:

true

policy · object · required

Policy governing what an agent can do, how it executes actions, and its spending boundaries.

Show child attributes

usage · object · required

Real-time counters tracking the agent's spending and transaction activity against its policy limits.

Show child attributes

createdAt · string<date-time> · required

Creation timestamp.

Example:

"2025-07-21T17:32:28Z"

updatedAt · string<date-time> · required

Last update timestamp.

Example:

"2025-07-21T17:32:28Z"

actingFor · string

The platform's reference for the person this agent acts for, as given when the agent was created. Absent when none was given.

Example:

"member_8f2c1a"

spendingPoolId · string

The spending pool the agent spends under, in addition to its own policy. Absent when the agent is in no pool.

Example:

"SpendingPool:019542f5-b3e7-1d02-0000-000000000007"