Update agent

Update an agent’s name, paused state or spending pool.

PATCH /agents/{agentId}

Update agent

cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Updated Payroll Agent",
  "isPaused": true,
  "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
}
'

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 basic fields. At least one field must be provided.

name · string

Updated name for the agent.

Example:

"Updated Payroll Agent"

isPaused · boolean

Set to true to pause the agent or false to resume it.

Example:

true

spendingPoolId · string | null

Move the agent to this spending pool of the same customer, or take it out of its pool with null. Available where the platform enables spending pools. The agent's policy must be in the pool's currency.

Example:

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

Response

200

application/json

Agent 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"