Agent Management

Create an agent

Changed on

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

Request

  • Base URL: https://api.lightspark.com/grid/2025-10-13
  • URL: https://api.lightspark.com/grid/2025-10-13/agents
  • Auth: HTTP basic

Request body

namestring required

Human-readable name to identify the agent.

customerIdstring required

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

Example request

{
  "name": "Payroll Automation Agent",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "policy": {
    "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
    }
  }
}

Response

Agent created successfully

Example response

{
  "agent": {
    "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "name": "Payroll Automation Agent",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "isConnected": true,
    "policy": {
      "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,
      "dailyResetDate": "2025-07-22",
      "monthlySpend": 750000,
      "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"
  }
}

Changes

  • 3966e5d38aadRevision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      added the new INSUFFICIENT_FUNDS enum value to the response property for the response status

    • warning

      added the new QUOTE_EXPIRED enum value to the response property for the response status

    • warning

      added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status

    • warning

      added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status

    • warning

      added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • 8964d9c7b6f9Revision changes
    • breaking

      removed the enum value CREATE_TRANSFERS of the request property //

    • info

      removed the CREATE_TRANSFERS enum value from the /// response property for the response status