Configuring Rules

Each workspace has a rules config — a JSON object that tells fluidsoul how to classify users. You can read and update it via the API.

API endpoints

GET  /v1/workspace/config    # Read current config
PUT  /v1/workspace/config    # Update config (replaces entire config)

Both require authentication (Bearer token + X-Workspace-Id header).

Full schema

{
  "dimensions": [
    {
      "name": "user_role",
      "values": ["analyst", "executive", "developer"],
      "default_value": "new_user",
      "hybrid_value": "hybrid"
    }
  ],
  "signals": [
    {
      "dimension": "user_role",
      "value": "analyst",
      "conditions": [
        { "field": "event_type", "equals": "report_viewed" },
        { "field": "metadata.role", "equals": "analyst" }
      ]
    },
    {
      "dimension": "user_role",
      "value": "executive",
      "conditions": [
        { "field": "event_type", "equals": "summary_viewed" },
        { "field": "metadata.role", "equals": "executive" }
      ]
    }
  ],
  "thresholds": {
    "dominant_ratio": 0.7
  },
  "feature_defaults": {
    "analyst": ["reports", "analytics", "data_export"],
    "executive": ["summary", "kpis", "reports"]
  },
  "recommended_defaults": {
    "analyst": {
      "default_view": "reports",
      "default_period": "weekly"
    },
    "executive": {
      "default_view": "summary",
      "default_period": "monthly"
    }
  },
  "engagement_thresholds": {
    "high": 15,
    "moderate": 5
  },
  "maturity_thresholds": {
    "power_user_breadth": 5,
    "power_user_days": 30,
    "intermediate_breadth": 3,
    "intermediate_days": 14
  }
}

Dimensions

A dimension is a classification axis. The first dimension is the primary one used for user_category and preferred_mode.

Field	Type	Description
`name`	string	Dimension name (e.g. `"user_role"`)
`values`	string[]	Possible values (e.g. `["analyst", "executive"]`)
`default_value`	string	Value when no signals match (default: `"new_user"`)
`hybrid_value`	string	Value when no clear dominant (default: `"hybrid"`)

Signals

Signals map events to dimension values. A signal matches if any of its conditions match.

Field	Type	Description
`dimension`	string	Which dimension this signal feeds
`value`	string	Which value to increment when matched
`conditions`	array	List of conditions (OR logic)

Conditions

Each condition checks a single field:

Field	Type	Description
`field`	string	`"event_type"` or `"metadata.<key>"`
`equals`	string	Value to match against

Thresholds

Field	Type	Default	Description
`dominant_ratio`	number	`0.7`	Ratio required for a clear classification

If the dominant value's ratio is below this threshold, the user is classified as the hybrid_value.

Feature defaults

A map from dimension value → ordered list of features. These are appended to the frequency-based priorities.

Recommended defaults

A map from dimension value → object of default settings. Returned as recommended_defaults in the context.

Engagement thresholds

Field	Type	Default	Description
`high`	number	`15`	Events in last 30 days for "high" engagement
`moderate`	number	`5`	Events in last 30 days for "moderate" engagement

Maturity thresholds

Field	Type	Default	Description
`power_user_breadth`	number	`5`	Unique event types for power user
`power_user_days`	number	`30`	Days active for power user
`intermediate_breadth`	number	`3`	Unique event types for intermediate
`intermediate_days`	number	`14`	Days active for intermediate

Empty config

If your workspace has an empty config ({}), fluidsoul falls back to a generic mode:

No dimension-based classification
user_category is set to "active_user"
Feature priorities are based on event type frequency only
Engagement and maturity still work with default thresholds

Example: update config via curl

curl -X PUT https://api.fluidsoul.dev/v1/workspace/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": [{
      "name": "user_type",
      "values": ["power_seller", "casual_buyer"],
      "default_value": "new_user",
      "hybrid_value": "mixed"
    }],
    "signals": [{
      "dimension": "user_type",
      "value": "power_seller",
      "conditions": [
        { "field": "event_type", "equals": "listing_created" },
        { "field": "metadata.role", "equals": "seller" }
      ]
    }],
    "thresholds": { "dominant_ratio": 0.6 },
    "feature_defaults": {
      "power_seller": ["listings", "analytics", "shipping"],
      "casual_buyer": ["search", "wishlist", "orders"]
    },
    "recommended_defaults": {
      "power_seller": { "default_view": "seller_dashboard" },
      "casual_buyer": { "default_view": "browse" }
    }
  }'

Configuring Rules

On this page