Create Rule

POST /api/v1/rules

Creates a new categorization rule.

Request Body

Field	Type	Required	Description
name	string	Yes	Rule name
description	string	No	Rule description
rationale	string	No	Why this rule exists (pattern observed, business logic)
priority	number	No	Execution priority (lower = first, default: 50)
conditions	array	No	Array of condition objects
actions	array	No	Array of action objects
enabled	boolean	No	Whether rule is active (default: true)

Condition Object

Field	Type	Description
field	string	Field to match (particulars, entity, category, etc.)
operator	string	Comparison operator
value	string	Value to match

Operators:

equals - Exact match (case-insensitive)
contains - Substring match
not_contains - Does not contain
starts_with - Prefix match
ends_with - Suffix match
regex - Regular expression match
is_null - Field is empty
is_not_null - Field has value

See Rule Object for the complete operator reference.

Action Object

Field	Type	Description
field	string	Transaction field to set
value	string	Value to set

Settable Fields:

category - Set the category field
entity - Set the entity field
type - Set the transaction type
comments - Add notes or tags for filtering/review

Example: Simple Category Rule

curl -X POST "https://statements.finopsbricks.com/api/v1/rules" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amazon Purchases",
    "conditions": [
      {"field": "particulars", "operator": "contains", "value": "AMAZON"}
    ],
    "actions": [
      {"field": "category", "value": "shopping"},
      {"field": "entity", "value": "Amazon"}
    ]
  }'

Example: Regex Rule with Priority

curl -X POST "https://statements.finopsbricks.com/api/v1/rules" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Utility Bills",
    "description": "Categorize electricity, water, and gas bills",
    "priority": 20,
    "conditions": [
      {
        "field": "particulars",
        "operator": "regex",
        "value": "(ELECTRICITY|WATER|GAS|BESCOM|BWSSB).*BILL"
      }
    ],
    "actions": [
      {"field": "category", "value": "utilities"}
    ]
  }'

Response

{
  "data": {
    "id": "rule456abc",
    "name": "Amazon Purchases",
    "description": null,
    "rationale": null,
    "priority": 50,
    "conditions": [
      {"field": "particulars", "operator": "contains", "value": "AMAZON"}
    ],
    "actions": [
      {"field": "category", "value": "shopping"},
      {"field": "entity", "value": "Amazon"}
    ],
    "enabled": true,
    "created_at": "2025-01-05T10:30:00.000Z",
    "updated_at": "2025-01-05T10:30:00.000Z"
  }
}

Errors

Code	Description
400	Validation error (missing name, invalid condition, invalid action)
401	Invalid or missing API credentials
403	API key lacks `rules:create` permission