Documentation Index
Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
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 |
weights map.
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 |
