> ## 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 API
> Create, update, list, and delete ranking profiles that define multi-objective scoring weights.
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](/self-host/architecture/engine) page for details on how ranking profiles are used during decision flow execution.
## Base path
```
/api/v1/ranking-profiles
```
***
## List ranking profiles
```
GET /api/v1/ranking-profiles
```
Returns all ranking profiles for the current tenant, ordered by creation date (newest first).
### Response `200`
```json theme={null}
[
{
"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. |
| `403` | Insufficient role. |
***
## Create a ranking profile
```
POST /api/v1/ranking-profiles
```
Creates a new ranking profile.
### 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. |
You can include any subset of these objectives. Additional custom objective names are also accepted in the `weights` map. All weight values are validated to the range `0..1`.
### Mapping into the formula (PRIE) score node
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 |
The `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](/decisioning/scoring-strategies) and
[PRIE — Design rationale](/decisioning/prie-formula-design).
### Example request
```json theme={null}
{
"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). |
| `401` | Missing or invalid API key / session. |
| `403` | Insufficient role (requires `editor` or `admin`). |
| `409` | A ranking profile with that `key` already exists (auto-generated keys collide when two profiles share a name). |
| `413` | Request body exceeds the 2 MB limit. |
| `415` | `Content-Type` is not `application/json`. |
***
## Update a ranking profile
```
PUT /api/v1/ranking-profiles
```
Updates an existing ranking profile. Only provided fields are changed.
### 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
```json theme={null}
{
"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. |
| `401` | Missing or invalid API key / session. |
| `403` | Insufficient role (requires `editor` or `admin`). |
| `404` | No ranking profile with that `id` (or name) in your tenant. |
| `413` | Request body exceeds the 2 MB limit. |
***
## Delete a ranking profile
```
DELETE /api/v1/ranking-profiles?id={profileId}
```
Deletes a ranking profile by ID.
### Query parameters
| Parameter | Required | Type | Description |
| --------- | -------- | ------ | --------------------- |
| `id` | **Yes** | string | Profile ID to delete. |
### Response `200`
```json theme={null}
{
"success": true,
"cascaded": 0
}
```
### Error codes
| Code | Reason |
| ----- | ----------------------------------------------------------- |
| `400` | Missing `id` query parameter or delete failed. |
| `401` | Missing or invalid API key / session. |
| `403` | Insufficient role (requires `admin`). |
| `404` | No ranking profile with that `id` (or name) in your tenant. |
***
## Role requirements
| Method | Minimum role |
| ------ | ------------ |
| GET | `viewer` |
| POST | `editor` |
| PUT | `editor` |
| DELETE | `admin` |