Update agent

Update an agent’s name or paused state.

PATCH /agents/{agentId}

cURL

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
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const agent = await client.agents.update('agentId');

console.log(agent.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.agents.Agent
import com.lightspark.grid.models.agents.AgentUpdateParams
import com.lightspark.grid.models.agents.AgentUpdateRequest

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: AgentUpdateParams = AgentUpdateParams.builder()
        .agentId("agentId")
        .agentUpdateRequest(AgentUpdateRequest.builder().build())
        .build()
    val agent: Agent = client.agents().update(params)
}

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": [],
    "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
    }
  },
  "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"
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

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

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"