Create an agent
curl --request POST \
--url https://api.lightspark.com/grid/2025-10-13/agents \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Payroll Automation Agent",
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"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
}
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Payroll Automation Agent',
customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
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}
}
})
};
fetch('https://api.lightspark.com/grid/2025-10-13/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));val client = OkHttpClient()
val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n \"name\": \"Payroll Automation Agent\",\n \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n \"policy\": {\n \"permissions\": [],\n \"spendingLimits\": {\n \"currency\": \"USD\",\n \"perTransactionLimit\": 50000,\n \"dailyLimit\": 500000,\n \"dailyTransactionLimit\": 10,\n \"monthlyLimit\": 5000000\n },\n \"accountRestrictions\": {\n \"allowedAccountIds\": [\n \"Account:019542f5-b3e7-1d02-0000-000000000001\"\n ],\n \"accountRules\": [\n {\n \"accountId\": \"Account:019542f5-b3e7-1d02-0000-000000000001\",\n \"perTransactionLimit\": 10000\n }\n ]\n },\n \"approvalThresholds\": {\n \"currency\": \"USD\",\n \"amount\": 100000\n }\n }\n}")
val request = Request.Builder()
.url("https://api.lightspark.com/grid/2025-10-13/agents")
.post(body)
.addHeader("Authorization", "Basic <encoded-value>")
.addHeader("Content-Type", "application/json")
.build()
val response = client.newCall(request).execute(){
"agent": {
"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"
},
"deviceCode": {
"code": "GRID-AGENT-X7K9-M2P4",
"agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
"expiresAt": "2025-07-22T17:32:28Z",
"redeemed": false
}
}{
"code": "INVALID_INPUT",
"reason": "<string>",
"details": {
"errors": [
{
"field": "identifier",
"constraint": {
"format": "email",
"pattern": "^\\d{5}(-\\d{4})?$",
"enum": [
"SSN",
"ITIN",
"NON_US_TAX_ID"
],
"minLength": 1,
"maxLength": 500
},
"message": "Value is not one of the allowed enum members."
}
]
}
}{
"code": "UNAUTHORIZED",
"reason": "<string>",
"details": {}
}{
"code": "GRID_SWITCH_ERROR",
"reason": "<string>",
"details": {}
}Agent Management
Create an agent
Create a new agent with a specified policy. Returns the created agent and a device code that must be redeemed by the agent software to complete installation.
POST
/
agents
Create an agent
curl --request POST \
--url https://api.lightspark.com/grid/2025-10-13/agents \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Payroll Automation Agent",
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"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
}
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Payroll Automation Agent',
customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
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}
}
})
};
fetch('https://api.lightspark.com/grid/2025-10-13/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));val client = OkHttpClient()
val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n \"name\": \"Payroll Automation Agent\",\n \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n \"policy\": {\n \"permissions\": [],\n \"spendingLimits\": {\n \"currency\": \"USD\",\n \"perTransactionLimit\": 50000,\n \"dailyLimit\": 500000,\n \"dailyTransactionLimit\": 10,\n \"monthlyLimit\": 5000000\n },\n \"accountRestrictions\": {\n \"allowedAccountIds\": [\n \"Account:019542f5-b3e7-1d02-0000-000000000001\"\n ],\n \"accountRules\": [\n {\n \"accountId\": \"Account:019542f5-b3e7-1d02-0000-000000000001\",\n \"perTransactionLimit\": 10000\n }\n ]\n },\n \"approvalThresholds\": {\n \"currency\": \"USD\",\n \"amount\": 100000\n }\n }\n}")
val request = Request.Builder()
.url("https://api.lightspark.com/grid/2025-10-13/agents")
.post(body)
.addHeader("Authorization", "Basic <encoded-value>")
.addHeader("Content-Type", "application/json")
.build()
val response = client.newCall(request).execute(){
"agent": {
"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"
},
"deviceCode": {
"code": "GRID-AGENT-X7K9-M2P4",
"agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
"expiresAt": "2025-07-22T17:32:28Z",
"redeemed": false
}
}{
"code": "INVALID_INPUT",
"reason": "<string>",
"details": {
"errors": [
{
"field": "identifier",
"constraint": {
"format": "email",
"pattern": "^\\d{5}(-\\d{4})?$",
"enum": [
"SSN",
"ITIN",
"NON_US_TAX_ID"
],
"minLength": 1,
"maxLength": 500
},
"message": "Value is not one of the allowed enum members."
}
]
}
}{
"code": "UNAUTHORIZED",
"reason": "<string>",
"details": {}
}{
"code": "GRID_SWITCH_ERROR",
"reason": "<string>",
"details": {}
}Authorizations
API token authentication using format <api token id>:<api client secret>
Body
application/json
Human-readable name to identify the agent.
Example:
"Payroll Automation Agent"
The ID of the customer this agent will operate on behalf of.
Example:
"Customer:019542f5-b3e7-1d02-0000-000000000001"
Policy governing what an agent can do, how it executes actions, and its spending boundaries.
Show child attributes
Show child attributes
Response
Agent created successfully
Was this page helpful?