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

cURL

cURL

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

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 agentCreateResponse = await client.agents.create({
  customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
  name: 'Payroll Automation Agent',
  policy: {
    defaultExecutionMode: 'AUTO',
    permissions: ['VIEW_TRANSACTIONS'],
    spendingLimits: { currency: 'USD', perTransactionLimit: 50000 },
  },
});

console.log(agentCreateResponse.agent);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.agents.AgentCreateRequest
import com.lightspark.grid.models.agents.AgentCreateResponse
import com.lightspark.grid.models.agents.AgentPolicy

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

    val params: AgentCreateRequest = AgentCreateRequest.builder()
        .customerId("Customer:019542f5-b3e7-1d02-0000-000000000001")
        .name("Payroll Automation Agent")
        .policy(AgentPolicy.builder()
            .defaultExecutionMode(AgentPolicy.DefaultExecutionMode.AUTO)
            .addPermission(AgentPolicy.Permission.VIEW_TRANSACTIONS)
            .spendingLimits(AgentPolicy.SpendingLimits.builder()
                .currency("USD")
                .perTransactionLimit(50000L)
                .build())
            .build())
        .build()
    val agentCreateResponse: AgentCreateResponse = client.agents().create(params)
}

201

{
  "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": [],
      "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"
  },
  "deviceCode": {
    "code": "GRID-AGENT-X7K9-M2P4",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "expiresAt": "2025-07-22T17:32:28Z",
    "redeemed": false
  }
}

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

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

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

Authorizations

Authorization · string · header · required

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

Body

application/json

name · string · required

Human-readable name to identify the agent.

Example:

"Payroll Automation Agent"

customerId · string · required

The ID of the customer this agent will operate on behalf of.

Example:

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

policy · object · required

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

Show child attributes

Response

201

application/json

Agent created successfully

Response returned when an agent is created, including the agent and a device code for installation.

agent · object · required

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

Show child attributes

deviceCode · object · required

Show child attributes