Rerank Controls

Rerank controls store per-context settings for the learned reranking layer. Configure them in the console when you need operators to manage the intended rerank mode, depth, and surface presets for a context.

How it works

The current product surface works like this:

Store controls on the context

Rerank controls are stored on the context record under json_data.rerank_controls.

Read and save through Platform API routes

The console reads and saves them through GET /api/rerank-controls and PUT /api/rerank-controls.

Gate rollout with feature flags

Feature flags such as RERANK_CONTROLS_STAGE, RERANK_KILL_SWITCH, and RERANK_MAX_DEPTH control rollout state in the console and resolver helper.

Serve through the Core API

Recommendation serving still goes through the Core API recommendation endpoint. There is no documented GET /api/recommendations Platform API route.

Configure in the console

Open Rerank Controls

Navigate to Console > Rerank Controls.

Open a context

Click a context row to open the editor.

Set the global default

Set the Global Default, the baseline mode and depth applied when no surface-specific preset matches.

Configure surface presets

Optionally configure Surface Presets to override behaviour for search, results, or recommendations surfaces independently.

Save changes

Save your changes.

Global defaults

Field	Description
Default Surface	The surface assumed when the caller does not specify one.
Rerank Mode	`off` (no reranking), `balanced` (moderate), or `aggressive` (strong personalisation, higher latency).
Rerank Depth	Number of candidates to rerank. Higher values improve quality at the cost of latency.

Surface presets

Each surface (search, results, recommendations) can override the global mode and depth. Surfaces that match the global default show as “inheriting” in the UI.

API access

Use a Platform API key with the admin scope to inspect or update saved controls:

curl "https://console.neuronsearchlab.com/api/rerank-controls?contextId=101" \
  -H "Authorization: Bearer nsl_..."

Feature flags and kill switch

Rerank controls support staged rollouts via environment variables:

Variable	Description
`RERANK_CONTROLS_STAGE`	`off`, `internal`, `canary`, or `general`. Controls who receives reranking.
`RERANK_KILL_SWITCH`	Set to `true` to immediately disable all reranking.
`RERANK_MAX_DEPTH`	Hard ceiling for rerank depth across all contexts.
`RERANK_INTERNAL_TEAM_IDS`	Comma-separated team IDs allowed during the `internal` stage.

When the kill switch is active or the stage is off, the resolver helper treats reranking as disabled and resolves rerank_mode: off with rerank_depth: 0.

Response shape

The Platform API returns context controls plus the current feature flags:

{
  "context": {
    "contextId": 101,
    "contextName": "Homepage Feed",
    "config": {
      "global_default": {
        "surface": "recommendations",
        "rerank_mode": "balanced",
        "rerank_depth": 80
      },
      "surface_presets": {
        "search": { "rerank_mode": "aggressive", "rerank_depth": 120 },
        "results": { "rerank_mode": "balanced", "rerank_depth": 80 },
        "recommendations": { "rerank_mode": "balanced", "rerank_depth": 80 }
      }
    }
  },
  "featureFlags": {
    "rerank_controls_stage": "general",
    "rerank_kill_switch": false,
    "rerank_max_depth": 200
  }
}

Get Started

Recommendation Control

NSL Connect

Console Workflow

Developer How-To

How it works

Configure in the console

Global defaults

Surface presets

API access

Feature flags and kill switch

Response shape

​How it works

​Configure in the console

​Global defaults

​Surface presets

​API access

​Feature flags and kill switch

​Response shape

How it works

Configure in the console

Global defaults

Surface presets

API access

Feature flags and kill switch

Response shape