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.
Portfolio optimization profiles (API path: arbitration-profiles for backward compatibility) 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 optimization profiles are used during decision flow execution. Base path
/api/v1/arbitration-profiles
List arbitration profiles
GET /api/v1/arbitration-profiles
Response 200
[
{
"id": "ap_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 an arbitration profile
POST /api/v1/arbitration-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 arbitration profile object.
Error codes
| Code | Reason |
|---|
400 | Validation error (missing name, weight out of range). |
415 | Content-Type is not application/json. |
Update an arbitration profile
PUT /api/v1/arbitration-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": "ap_001",
"weights": {
"revenue": 0.3,
"margin": 0.3,
"propensity": 0.3,
"engagement": 0.1
}
}
Response 200
Returns the updated arbitration profile object.
Error codes
| Code | Reason |
|---|
400 | Validation error. |
Delete an arbitration profile
DELETE /api/v1/arbitration-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 |
