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

# Features V1

Enrich items with ML-computed features based on user profile and preferences.

This endpoint computes personalized features for a list of items by comparing them against a user's profile. The computed features are designed to be used as inputs to the Ranking pipeline.

**Semantic Features**:
- Dense vector similarity between user and item embeddings (cosine similarity)
- Multiple embedding comparisons: `sem_sim_1` through `sem_sim_5` for primary through fifth user embeddings
- `sem_sim_fuzzy`: Loose matching across all embeddings
- `sem_sim_closest`: Maximum similarity across all user embeddings
- Cluster indicators (`sem_sim_cluster1`–`sem_sim_cluster5`): Binary flags indicating which user embedding is the closest match

**Topic Features**:
- `usr_primary_labels` / `usr_primary_tags`: Count of matching labels/tags against user's primary preferences
- `usr_secondary_labels` / `usr_secondary_tags`: Count against secondary preferences
- `usr_mixed_labels` / `usr_mixed_tags`: Weighted blend (75% primary + 25% secondary)
- `AI:*` / `TAG:*`: One-hot encoded features for individual labels and tags

**Composite Features**:
- `topic_similarity`: Combined score aggregating semantic and topic signals
- `original_rank`: Normalized position from request order (0–1, higher = earlier)

**Index-Specific Features** (Polymarket):
- `num_bets`: Number of bets on the market
- `num_price_changes`: Number of price change events

All numerical features are normalized to [0, 1] range for consistent scaling.


# 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": "Features",
      "description": "## Overview\n\nThe Features service enriches candidate items with ML-computed personalization signals by comparing each item against a user's profile.\n\n## Key Concepts\n\n- **Semantic Features**: Cosine similarity between user and item embedding vectors (primary, secondary, tertiary, etc.), plus a `sem_sim_closest` maximum across all user embeddings.\n- **Topic Features**: Label and tag matching between user preferences and item metadata — `usr_primary_labels`, `usr_secondary_labels`, `usr_mixed_labels` (75/25 weighted blend), and corresponding tag features.\n- **Composite Features**: `topic_similarity` aggregates semantic and topic signals into a single score.\n- **One-Hot Features**: `AI:*` and `TAG:*` binary features for each label/tag on the item, enabling downstream models to use individual signals.\n- **Index-Specific Features**: Polymarket items include `num_bets` and `num_price_changes`.\n\n## Usage\n\nPass a user profile (`index` + `id`) and a list of items. The service retrieves user embeddings and preferences from DynamoDB, computes all features, and returns them keyed by index and item ID. Features are normalized to [0, 1] for consistent scaling. Use these features as inputs to the Ranking pipeline's sort/linear/mix methods.\n"
    }
  ],
  "paths": {
    "/features/v1": {
      "post": {
        "operationId": "computeFeaturesV1",
        "tags": [
          "Features"
        ],
        "summary": "Version 1",
        "description": "Enrich items with ML-computed features based on user profile and preferences.\n\nThis endpoint computes personalized features for a list of items by comparing them against a user's profile. The computed features are designed to be used as inputs to the Ranking pipeline.\n\n**Semantic Features**:\n- Dense vector similarity between user and item embeddings (cosine similarity)\n- Multiple embedding comparisons: `sem_sim_1` through `sem_sim_5` for primary through fifth user embeddings\n- `sem_sim_fuzzy`: Loose matching across all embeddings\n- `sem_sim_closest`: Maximum similarity across all user embeddings\n- Cluster indicators (`sem_sim_cluster1`–`sem_sim_cluster5`): Binary flags indicating which user embedding is the closest match\n\n**Topic Features**:\n- `usr_primary_labels` / `usr_primary_tags`: Count of matching labels/tags against user's primary preferences\n- `usr_secondary_labels` / `usr_secondary_tags`: Count against secondary preferences\n- `usr_mixed_labels` / `usr_mixed_tags`: Weighted blend (75% primary + 25% secondary)\n- `AI:*` / `TAG:*`: One-hot encoded features for individual labels and tags\n\n**Composite Features**:\n- `topic_similarity`: Combined score aggregating semantic and topic signals\n- `original_rank`: Normalized position from request order (0–1, higher = earlier)\n\n**Index-Specific Features** (Polymarket):\n- `num_bets`: Number of bets on the market\n- `num_price_changes`: Number of price change events\n\nAll numerical features are normalized to [0, 1] range for consistent scaling.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeaturesV1Request"
              },
              "examples": {
                "basic": {
                  "summary": "Basic feature computation for polymarket items",
                  "value": {
                    "user": {
                      "index": "polymarket-wallets",
                      "id": "0xea80ca47759ef8af31229b360848c62d98ae35fb"
                    },
                    "items": [
                      {
                        "index": "polymarket-items",
                        "id": "0x1234567890abcdef"
                      },
                      {
                        "index": "polymarket-items",
                        "id": "0xabcdef1234567890"
                      },
                      {
                        "index": "polymarket-items",
                        "id": "0xfedcba0987654321"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully computed features for items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeaturesV1Response"
                },
                "examples": {
                  "success": {
                    "summary": "Successful feature computation result",
                    "value": {
                      "result": {
                        "user": {
                          "_index": "polymarket-wallets",
                          "_id": "0xea80ca47759ef8af31229b360848c62d98ae35fb",
                          "_source": {
                            "user_id": "0xea80ca47759ef8af31229b360848c62d98ae35fb",
                            "primary_labels": [
                              "mbd2:f_bullish",
                              "mbd2:t_crypto"
                            ],
                            "secondary_labels": [
                              "mbd2:f_neutral"
                            ]
                          }
                        },
                        "items": {
                          "polymarket-items": {
                            "0x1234567890abcdef": {
                              "found": 1,
                              "original_rank": 1,
                              "sem_sim_fuzzy": 0.85,
                              "sem_sim_closest": 0.88,
                              "usr_primary_labels": 1,
                              "usr_primary_tags": 0.5,
                              "usr_secondary_labels": 0.3,
                              "usr_secondary_tags": 0.2,
                              "usr_mixed_labels": 0.8,
                              "usr_mixed_tags": 0.4,
                              "topic_similarity": 3.5,
                              "num_bets": 15,
                              "num_price_changes": 42
                            }
                          }
                        },
                        "feature_names": [
                          "found",
                          "original_rank",
                          "sem_sim_fuzzy",
                          "sem_sim_closest",
                          "usr_primary_labels",
                          "usr_primary_tags",
                          "topic_similarity",
                          "num_bets",
                          "num_price_changes"
                        ],
                        "hit_rate": 0.95,
                        "user_embed": true,
                        "item_embed_rate": 0.92,
                        "took_dynamo_user": 45,
                        "took_dynamo_items": 120,
                        "took_semantic": 15,
                        "took_topics": 8,
                        "took_features": 50,
                        "took_backend": 230
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeaturesV1Error"
                },
                "examples": {
                  "missing_user": {
                    "summary": "Missing user in request",
                    "value": {
                      "error": "user is required"
                    }
                  },
                  "user_not_found": {
                    "summary": "User not found in DynamoDB",
                    "value": {
                      "error": "user was not found in DynamoDB"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeaturesV1Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Console API key. Use `Bearer mbd-{your-api-key}`."
      }
    },
    "schemas": {
      "FeaturesV1Request": {
        "type": "object",
        "required": [
          "user",
          "items"
        ],
        "description": "Request payload for the Features V1 endpoint. Specifies a user profile and a list of items to enrich with ML-computed features.\n\n**User Specification**:\n- Provide a user profile using `user.index` (DynamoDB table/index) and `user.id` (user identifier)\n- The service retrieves user data including preferences, embeddings, and profile information\n\n**Item Enrichment**:\n- Provide a list of items with `items[].index` and `items[].id`\n- Original rank is preserved based on position in the request list\n- Items are retrieved from DynamoDB for their content and metadata\n\n**Supported User Indices**: `polymarket-wallets`\n**Supported Item Indices**: `polymarket-items`\n",
        "properties": {
          "user": {
            "type": "object",
            "required": [
              "index",
              "id"
            ],
            "description": "User profile specification for feature computation",
            "properties": {
              "index": {
                "type": "string",
                "description": "DynamoDB index/table name containing user data",
                "enum": [
                  "polymarket-wallets"
                ],
                "example": "polymarket-wallets"
              },
              "id": {
                "type": "string",
                "description": "Unique identifier of the user within the index (e.g., wallet address)",
                "example": "0xea80ca47759ef8af31229b360848c62d98ae35fb"
              }
            }
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "description": "List of items to enrich with features. Order matters — `original_rank` is calculated from position in this list.",
            "items": {
              "type": "object",
              "required": [
                "index",
                "id"
              ],
              "properties": {
                "index": {
                  "type": "string",
                  "description": "DynamoDB index/table name containing the item",
                  "enum": [
                    "polymarket-items"
                  ],
                  "example": "polymarket-items"
                },
                "id": {
                  "type": "string",
                  "description": "Unique identifier of the item within the index",
                  "example": "0x1234567890abcdef"
                }
              }
            },
            "example": [
              {
                "index": "polymarket-items",
                "id": "0x123abc"
              },
              {
                "index": "polymarket-items",
                "id": "0x456def"
              }
            ]
          }
        }
      },
      "FeaturesV1Response": {
        "type": "object",
        "description": "Response containing enriched item features, user profile data, and computation timing metrics.",
        "properties": {
          "result": {
            "type": "object",
            "description": "Feature computation results and metrics",
            "properties": {
              "user": {
                "type": "object",
                "description": "User profile information and metadata",
                "properties": {
                  "_index": {
                    "type": "string",
                    "description": "DynamoDB index where user data was retrieved",
                    "example": "polymarket-wallets"
                  },
                  "_id": {
                    "type": "string",
                    "description": "User identifier",
                    "example": "0xea80ca47759ef8af31229b360848c62d98ae35fb"
                  },
                  "_source": {
                    "type": "object",
                    "description": "Raw user attributes from DynamoDB",
                    "additionalProperties": true
                  }
                }
              },
              "items": {
                "type": "object",
                "description": "Computed features indexed by DynamoDB index, then by item ID. Each item maps to an object of feature name/value pairs.",
                "additionalProperties": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "object",
                    "description": "Feature values for a single item",
                    "properties": {
                      "found": {
                        "type": "integer",
                        "description": "1 if item was found in DynamoDB, 0 otherwise",
                        "enum": [
                          0,
                          1
                        ],
                        "example": 1
                      },
                      "original_rank": {
                        "type": "number",
                        "description": "Normalized rank from request position (0–1, higher = earlier)",
                        "example": 1
                      },
                      "sem_sim_fuzzy": {
                        "type": "number",
                        "description": "Semantic similarity — fuzzy/loose matching across all user embeddings",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "sem_sim_1": {
                        "type": "number",
                        "description": "Cosine similarity to user's primary embedding",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "sem_sim_2": {
                        "type": "number",
                        "description": "Cosine similarity to user's secondary embedding",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "sem_sim_3": {
                        "type": "number",
                        "description": "Cosine similarity to user's tertiary embedding",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "sem_sim_4": {
                        "type": "number",
                        "description": "Cosine similarity to user's fourth embedding",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "sem_sim_5": {
                        "type": "number",
                        "description": "Cosine similarity to user's fifth embedding",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "sem_sim_closest": {
                        "type": "number",
                        "description": "Maximum similarity across all user embeddings (best match)",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "sem_sim_cluster1": {
                        "type": "number",
                        "description": "Binary: 1 if closest match is primary embedding, 0 otherwise"
                      },
                      "sem_sim_cluster2": {
                        "type": "number",
                        "description": "Binary: 1 if closest match is secondary embedding"
                      },
                      "sem_sim_cluster3": {
                        "type": "number",
                        "description": "Binary: 1 if closest match is tertiary embedding"
                      },
                      "sem_sim_cluster4": {
                        "type": "number",
                        "description": "Binary: 1 if closest match is fourth embedding"
                      },
                      "sem_sim_cluster5": {
                        "type": "number",
                        "description": "Binary: 1 if closest match is fifth embedding"
                      },
                      "usr_primary_labels": {
                        "type": "number",
                        "description": "Count of matching labels with user's primary label preferences"
                      },
                      "usr_primary_tags": {
                        "type": "number",
                        "description": "Count of matching tags with user's primary tag preferences"
                      },
                      "usr_secondary_labels": {
                        "type": "number",
                        "description": "Count of matching labels with user's secondary label preferences"
                      },
                      "usr_secondary_tags": {
                        "type": "number",
                        "description": "Count of matching tags with user's secondary tag preferences"
                      },
                      "usr_mixed_labels": {
                        "type": "number",
                        "description": "Weighted blend of primary (75%) and secondary (25%) label matches"
                      },
                      "usr_mixed_tags": {
                        "type": "number",
                        "description": "Weighted blend of primary (75%) and secondary (25%) tag matches"
                      },
                      "topic_similarity": {
                        "type": "number",
                        "description": "Composite score combining semantic and topic features",
                        "minimum": 0
                      },
                      "num_bets": {
                        "type": "number",
                        "description": "Number of bets on this market (Polymarket-specific)"
                      },
                      "num_price_changes": {
                        "type": "number",
                        "description": "Number of price change events (Polymarket-specific)"
                      }
                    }
                  }
                }
              },
              "feature_names": {
                "type": "array",
                "description": "List of all computed feature names in results",
                "items": {
                  "type": "string"
                },
                "example": [
                  "found",
                  "original_rank",
                  "sem_sim_fuzzy",
                  "sem_sim_closest",
                  "usr_primary_labels",
                  "topic_similarity"
                ]
              },
              "hit_rate": {
                "type": "number",
                "description": "Fraction of items found in DynamoDB (0–1)",
                "minimum": 0,
                "maximum": 1,
                "example": 0.95
              },
              "user_embed": {
                "type": "boolean",
                "description": "Whether user has embeddings available for semantic similarity",
                "example": true
              },
              "item_embed_rate": {
                "type": "number",
                "description": "Fraction of items with embeddings available (0–1)",
                "minimum": 0,
                "maximum": 1,
                "example": 0.9
              },
              "took_dynamo_user": {
                "type": "integer",
                "description": "Time retrieving user data from DynamoDB (ms)",
                "example": 45
              },
              "took_dynamo_items": {
                "type": "integer",
                "description": "Time retrieving items from DynamoDB (ms)",
                "example": 120
              },
              "took_semantic": {
                "type": "integer",
                "description": "Time computing semantic similarity features (ms)",
                "example": 15
              },
              "took_topics": {
                "type": "integer",
                "description": "Time computing topic-based features (ms)",
                "example": 8
              },
              "took_features": {
                "type": "integer",
                "description": "Total time computing all features (ms)",
                "example": 50
              },
              "took_backend": {
                "type": "integer",
                "description": "Total end-to-end processing time (ms)",
                "example": 230
              }
            }
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Error message if request processing failed"
          }
        }
      },
      "FeaturesV1Error": {
        "type": "object",
        "description": "Error response from the Features service.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error description",
            "example": "user was not found in DynamoDB"
          }
        }
      }
    }
  }
}
```