Ranking profiles define how the platform balances competing business objectives (revenue, margin, propensity, engagement, etc.) when ranking offers. Each profile specifies a set of weights that the optimization engine uses to compute a composite score via the Optimize pipeline node.
See the Architecture — Engine page for details on how ranking profiles are used during decision flow execution. Base path
List ranking profiles
GET /api/v1/ranking-profiles
Response 200
[
{
"id": "rp_001",
"tenantId": "t_001",
"name": "Revenue Focused",
"description": "Prioritize revenue-generating offers.",
"weights": {
"revenue": 0.5,
"margin": 0.2,
"propensity": 0.2,
"engagement": 0.1
},
"key": "revenue-focused",
"createdAt": "2026-03-10T12:00:00.000Z",
"updatedAt": "2026-03-12T09:30:00.000Z"
}
]
Error codes
| Code | Reason |
|---|
401 | Missing or invalid API key. |
Create a ranking profile
POST /api/v1/ranking-profiles
Request body
| Field | Required | Type | Description |
|---|
name | Yes | string (1-200) | Unique profile name. |
key | No | string (1-100) | URL-safe identifier (lowercase alphanumeric, hyphens, underscores). Auto-generated from name if omitted. |
description | No | string (max 1000) | Profile description. Default "". |
weights | No | object | Map of objective names to weight values (0-1). Default {}. |
Weight values must be between 0 and 1 (not percentages). While they do not need to sum to 1, it is recommended for interpretability.
Standard objectives
The following objective names are supported in the weights map:
| Objective | Description |
|---|
propensity | Model-predicted likelihood of positive outcome |
relevance | Contextual relevance to the customer |
impact | Business value / revenue potential |
emphasis | Manual priority boost |
diversity | Catalog diversity in recommendations |
clv | Customer-lifetime-value emphasis (default 0). Linear scorer objective; also feeds the formula score node’s CLV term. |
weights map. All weight values are validated to the range 0..1.
When a formula-method Score node references a profile via strategyProfileId,
the profile’s weight keys map into the PRIE formula:
| Profile key | PRIE term |
|---|
conversion | propensityWeight (Wp) |
recency | relevanceWeight (Wr) |
margin | impactWeight (Wi) |
fairness | emphasisWeight (We) |
uplift | upliftWeight — optional exponent term, default 0 |
clv | clvWeight — optional exponent term, default 0 |
uplift and clv keys are exponent terms outside the P+R+I+E sum-to-1
constraint, each ranging 0..1 when set through a profile (0..2 in the inline
formula config). Studio surfaces both as sliders under Scoring Strategies.
See Scoring strategies and
PRIE — Design rationale.
Example request
{
"name": "Revenue Focused",
"description": "Prioritize revenue-generating offers.",
"weights": {
"revenue": 0.5,
"margin": 0.2,
"propensity": 0.2,
"engagement": 0.1
}
}
Response 201
Returns the created ranking profile object.
Error codes
| Code | Reason |
|---|
400 | Validation error (missing name, weight out of range). |
415 | Content-Type is not application/json. |
Update a ranking profile
PUT /api/v1/ranking-profiles
Request body
| Field | Required | Type | Description |
|---|
id | Yes | string | The profile ID to update. |
name | No | string (1-200) | Updated name. |
description | No | string (max 1000) | Updated description. |
weights | No | object | Updated weight map. |
Example request
{
"id": "rp_001",
"weights": {
"revenue": 0.3,
"margin": 0.3,
"propensity": 0.3,
"engagement": 0.1
}
}
Response 200
Returns the updated ranking profile object.
Error codes
| Code | Reason |
|---|
400 | Validation error. |
Delete a ranking profile
DELETE /api/v1/ranking-profiles?id={profileId}
Query parameters
| Parameter | Required | Type | Description |
|---|
id | Yes | string | Profile ID to delete. |
Response 200
{
"success": true,
"cascaded": 0
}
Error codes
| Code | Reason |
|---|
400 | Missing id query parameter or delete failed. |
Role requirements
| Method | Minimum role |
|---|
| GET | viewer |
| POST | editor |
| PUT | editor |
| DELETE | admin |
