Create a new rule

Endpoint

POST https://api.sapiom.ai/v1/spending-rules

Authentication

Requires Bearer authentication — pass a JWT token or API key in the Authorization header.

Request Body

Field Reference

ruleType — Type of rule:

Value	Description
`usage_limit`	Limit based on count or amount thresholds
`spending_limit`	Alias for usage_limit with spend focus

conditions[].fieldType — What dimension to evaluate:

Value	Description
`service`	Match by service name (e.g., “openai”, “linkup”)
`action`	Match by action type
`resource`	Match by resource identifier
`qualifier`	Match by qualifier value
`transaction_property`	Match by transaction metadata
`payment_property`	Match by payment metadata

conditions[].operator — Comparison operator:

Value	Description
`equals`	Exact match
`not_equals`	Does not match
`contains`	Contains substring
`not_contains`	Does not contain substring
`greater_than`	Numeric greater than
`less_than`	Numeric less than

parameters[].measurementType — What to measure:

Value	Description
`count_transactions`	Count of transactions
`sum_payment_amount`	Sum of payment amounts in USD (most common for budget caps)
`this_payment_amount`	Amount of the current payment
`sum_transaction_costs`	Sum of transaction costs
`this_transaction_cost`	Cost of the current transaction

parameters[].intervalUnit — Time window:

Value	Description
`minutes`	Per-minute window
`hours`	Per-hour window
`days`	Per-day window
`weeks`	Per-week window
`months`	Per-month window

agentIds — Optional array of agent UUIDs. When set, the rule only applies to these specific agents. Omit to apply to all agents in the tenant.

Example: Daily Dollar Budget Cap

The most common use case — limit an agent to $10/day:

{
  "name": "$10 daily budget",
  "ruleType": "usage_limit",
  "resolutionStrategy": "automatic",
  "conditions": [],
  "parameters": [
    {
      "parameterName": "Daily spend cap",
      "limitValue": "10",
      "measurementType": "sum_payment_amount",
      "intervalValue": 24,
      "intervalUnit": "hours",
      "isRolling": true,
      "groupBy": ["agent"],
      "measurementScope": "all",
      "description": "Cap total spend at $10 per 24h"
    }
  ],
  "agentIds": ["550e8400-e29b-41d4-a716-446655440000"]
}

Example: Transaction Count Limit

{
  "name": "Daily transaction limit",
  "ruleType": "usage_limit",
  "resolutionStrategy": "automatic",
  "conditions": [
    {
      "fieldType": "service",
      "fieldName": "openai",
      "operator": "equals",
      "value": "openai",
      "conditionGroup": "primary"
    }
  ],
  "parameters": [
    {
      "parameterName": "Max daily transactions",
      "limitValue": "100",
      "measurementType": "count_transactions",
      "intervalValue": 24,
      "intervalUnit": "hours",
      "isRolling": true,
      "groupBy": ["agent"],
      "measurementScope": "all",
      "description": "Limits total API calls per day"
    }
  ],
  "agentIds": ["550e8400-e29b-41d4-a716-446655440000"]
}

cURL Example

curl -X POST "https://api.sapiom.ai/v1/spending-rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily spending limit",
    "ruleType": "usage_limit",
    "resolutionStrategy": "automatic",
    "metadata": {
        "category": "finance"
    },
    "conditions": [
        {
            "fieldType": "service",
            "fieldName": "openai",
            "operator": "equals",
            "value": "openai",
            "conditionGroup": "primary"
        }
    ],
    "parameters": [
        {
            "parameterName": "Max daily transactions",
            "limitValue": "100",
            "measurementType": "count_transactions",
            "intervalValue": 24,
            "intervalUnit": "hours",
            "isRolling": true,
            "groupBy": [
                "agent"
            ],
            "measurementScope": "all",
            "description": "Limits total API calls per day"
        }
    ],
    "agentIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}'

Response

{
  "id": "string",
  "tenantId": "string",
  "numericId": 0,
  "formattedId": "string",
  "name": "string",
  "ruleType": "usage_limit",
  "resolutionStrategy": "automatic",
  "status": "active",
  "version": 0,
  "metadata": null,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Error Responses

Status	Code	Description
400	-	Invalid request data
401	-	Unauthorized - invalid or missing authentication
403	-	Forbidden - insufficient permissions

See API Introduction for error handling details.