---
updatedAt: 2026-07-06T21:17:35.000Z
agentTools:
  projectIndex: https://docs.getembed.ai/llms.txt
---

# Rerank

Rerank a list of item IDs for a given user using a trained ML model.

This endpoint sends the user and items to a trained ranking model, which returns the same items in a personalized order based on predicted relevance.

**Flow**:
1. Provide `user_id` and `item_ids` in the request body
2. The service reranks items using the trained model for the given `model_name`
3. Response returns the same item IDs in a new order (personalized ranking)

**Available Models**:
- `polymarket-rerank-v1` — Polymarket reranking model trained on trading activity data

**Error Handling**:
Errors are returned with HTTP 200 and an `error` field in the response body (rather than HTTP error codes). This includes:
- Missing `user_id` or `item_ids`
- Unknown `model_name`
- Service errors (model not found, invalid input, network issues)


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Studio APIs",
    "version": "1.0.0",
    "description": "The Studio APIs are the building-block services developers use to construct personalized feeds. Each endpoint handles one stage of the feed pipeline, and they are designed to be composed together:\n\n1. **Search** — Generate candidate items from Elasticsearch indices (Farcaster, Polymarket, Zora, Kalshi, Token) using filters, boosting, or semantic similarity.\n2. **Features** — Enrich candidates with ML-computed features (semantic similarity, topic matching, composite scores) based on a user profile.\n3. **Scoring** — Rerank candidates using trained ML models for personalized ordering.\n4. **Ranking** — Apply a 3-stage post-processing pipeline (sort, diversity, limits-by-field) to produce the final feed.\n5. **Stories** — Generate personalized narrative-driven content about market activity, bets, and price movements.\n\nThe typical flow is: **Search → Features → Scoring → Ranking**, with Stories as an optional parallel path for narrative content.\n\nThe [Algorithm DSL](https://www.npmjs.com/package/algo-dsl) wraps these endpoints with a fluent builder API, but you can also call them directly via REST.\n",
    "contact": {
      "name": "embed Team",
      "url": "https://www.mbd.xyz"
    },
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.mbd.xyz/v3/studio",
      "description": "embed Studio API"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Scoring",
      "description": "## Overview\n\nThe Scoring service reranks candidate items using trained machine learning models. Given a user and a list of items, it returns the same items in a new personalized order.\n\n## Key Concepts\n\n- **Ranking Models**: Each model is trained on user interaction data to produce personalized rankings.\n- **Available Models**: `polymarket-rerank-v1` — a reranking model trained on Polymarket trading activity.\n- **Score Conversion**: The SDK converts the returned ranked order into a [0, 1] score (`1.0` for the top-ranked item, decreasing linearly).\n\n## Usage\n\nProvide a `user_id` (e.g., wallet address) and `item_ids` array. The service returns the item IDs in personalized order. Errors (missing user, unknown model, service failures) are returned in the response body with a 200 status code rather than HTTP error codes.\n"
    }
  ],
  "paths": {
    "/scoring/ranking_model/{model_name}": {
      "post": {
        "operationId": "scoringRankingModel",
        "tags": [
          "Scoring"
        ],
        "summary": "Rerank",
        "description": "Rerank a list of item IDs for a given user using a trained ML model.\n\nThis endpoint sends the user and items to a trained ranking model, which returns the same items in a personalized order based on predicted relevance.\n\n**Flow**:\n1. Provide `user_id` and `item_ids` in the request body\n2. The service reranks items using the trained model for the given `model_name`\n3. Response returns the same item IDs in a new order (personalized ranking)\n\n**Available Models**:\n- `polymarket-rerank-v1` — Polymarket reranking model trained on trading activity data\n\n**Error Handling**:\nErrors are returned with HTTP 200 and an `error` field in the response body (rather than HTTP error codes). This includes:\n- Missing `user_id` or `item_ids`\n- Unknown `model_name`\n- Service errors (model not found, invalid input, network issues)\n",
        "parameters": [
          {
            "name": "model_name",
            "in": "path",
            "required": true,
            "description": "Name of the ranking model (campaign) to use",
            "schema": {
              "type": "string",
              "enum": [
                "polymarket-rerank-v1"
              ]
            },
            "example": "polymarket-rerank-v1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScoringRankingModelRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Rerank Polymarket items for a user",
                  "value": {
                    "user_id": "0xd9eb76925a0a233bcde74e22dc93727237188bab",
                    "item_ids": [
                      "1289113",
                      "1288428",
                      "1287500"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reranked list or error (service returns 200 with body containing either result or error)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ScoringRankingModelResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ScoringRankingModelError"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Successful reranking",
                    "value": {
                      "result": [
                        "1288428",
                        "1289113",
                        "1287500"
                      ]
                    }
                  },
                  "error_missing_user": {
                    "summary": "Missing user_id",
                    "value": {
                      "error": "user_id is required"
                    }
                  },
                  "error_unknown_model": {
                    "summary": "Unknown model name",
                    "value": {
                      "error": "Model ID 'unknown' not found in MODELS. Available models: ['polymarket-rerank-v1']"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScoringRankingModelError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Console API key. Use `Bearer mbd-{your-api-key}`."
      }
    },
    "schemas": {
      "ScoringRankingModelRequest": {
        "type": "object",
        "required": [
          "user_id",
          "item_ids"
        ],
        "description": "Request body for the Scoring rerank endpoint. Provides a user and list of items to be reranked using a trained ML model.",
        "properties": {
          "user_id": {
            "type": "string",
            "description": "Unique identifier of the user (e.g., wallet address for Polymarket)",
            "example": "0xd9eb76925a0a233bcde74e22dc93727237188bab"
          },
          "item_ids": {
            "type": "array",
            "minItems": 1,
            "description": "Ordered list of item IDs to rerank. Personalize returns a new order based on predicted relevance.",
            "items": {
              "type": "string"
            },
            "example": [
              "1289113",
              "1288428",
              "1287500"
            ]
          }
        }
      },
      "ScoringRankingModelResponse": {
        "type": "object",
        "description": "Success response from the Scoring rerank endpoint. Contains the reranked item IDs.",
        "properties": {
          "result": {
            "type": "array",
            "description": "Reranked item IDs in descending order of predicted relevance",
            "items": {
              "type": "string"
            },
            "example": [
              "1288428",
              "1289113",
              "1287500"
            ]
          },
          "error": {
            "type": "string",
            "description": "Present only when an error occurred; absent on success",
            "example": null
          }
        }
      },
      "ScoringRankingModelError": {
        "type": "object",
        "description": "Error response from the Scoring service. Returned with HTTP 200 status.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message (validation, model not found, AWS failure)",
            "example": "user_id is required"
          }
        }
      }
    }
  }
}
```