Ranking Profiles API

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

/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`

[
  {
    "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 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).
`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

{
  "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`

{
  "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`

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Ranking Profiles API

Base path

List ranking profiles

Response `200`

Error codes

Create a ranking profile

Request body

Standard objectives

Mapping into the formula (PRIE) score node

Example request

Response `201`

Error codes

Update a ranking profile

Request body

Example request

Response `200`

Error codes

Delete a ranking profile

Query parameters

Response `200`

Error codes

Role requirements

​Base path

​List ranking profiles

​Response 200

​Error codes

​Create a ranking profile

​Request body

​Standard objectives

​Mapping into the formula (PRIE) score node

​Example request

​Response 201

​Error codes

​Update a ranking profile

​Request body

​Example request

​Response 200

​Error codes

​Delete a ranking profile

​Query parameters

​Response 200

​Error codes

​Role requirements

Base path

List ranking profiles

Response `200`

Error codes

Create a ranking profile

Request body

Standard objectives

Mapping into the formula (PRIE) score node

Example request

Response `201`

Error codes

Update a ranking profile

Request body

Example request

Response `200`

Error codes

Delete a ranking profile

Query parameters

Response `200`

Error codes

Role requirements