--- updatedAt: 2026-03-30T12:48:23.000Z agentTools: projectIndex: https://docs.getembed.ai/llms.txt --- # Semantic Search Execute a semantic similarity search using dense vector embeddings. This endpoint retrieves items by meaning rather than exact keyword matching. It supports two modes: **Text Mode**: - Provide a text string (minimum 5 characters) - The server generates a 768-dimensional embedding using the multilingual-e5-small model - Results are ranked by cosine similarity to the generated embedding **Vector Mode**: - Provide a pre-computed 768-dimensional vector - Useful when you have embeddings from another source or want to cache/reuse them - Results are ranked by cosine similarity to your provided vector You must provide either `text` OR `vector`, but not both. **Result Ordering**: Results are ordered by similarity score (highest first). Scores represent cosine similarity between the query and document vectors, ranging from 0.0 to 1.0 where 1.0 is identical. # 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": "Search", "description": "## Overview\n\nThe Search service generates candidate items from Elasticsearch indices. It supports four endpoints covering different retrieval strategies: filter-and-sort for structured queries, boost for relevance tuning, semantic for embedding-based similarity, and frequent-values for field exploration.\n\n## Key Concepts\n\n- **Indices**: Seven content indices are available — `polymarket-items` (social posts), `polymarket-items` (prediction markets), `polymarket-wallets` (Polymarket user wallets/profiles), `token-items` (creator coins), `kalshi-notifications` (Kalshi prediction markets via DFlow on Solana), `polymarket-wallets` (Kalshi user wallets/profiles), and `token-items` (multi-chain token data across Base, Ethereum, and Solana). Each index has its own set of filterable and sortable fields. See [Supported Indices](../docs/Data-Sources/supported-indices) for the full field reference.\n- **Filter Logic**: Filters go into `include` (AND — all must match), `exclude` (NOT — any match removes the item), or `boost` (SHOULD — matching items get a relevance multiplier) arrays.\n- **Filter Types**: 12 filter types are available — `term`, `terms`, `numeric`, `match`, `date`, `geo`, `is_null`, `not_null`, `custom`, `group_boost`, `terms_lookup`, and `console_account`.\n- **AI Labels**: Items are classified by MBD's AI pipeline into topics, sentiment, emotion, moderation, Web3, market sentiment, and content quality categories at three confidence levels (`ai_labels_high`, `ai_labels_med`, `ai_labels_low`).\n\n## Usage\n\nStart by choosing an index and a search mode. Use **Filter and Sort** for structured queries with exact filters and field-based ordering. Use **Boost** when you want soft relevance tuning without hard filtering. Use **Semantic** when you have a text query or embedding vector and want similarity-based retrieval. Use **Frequent Values** to discover what values exist in a field before building filters.\n" } ], "paths": { "/search/semantic": { "post": { "operationId": "searchSemantic", "tags": [ "Search" ], "summary": "Semantic Search", "description": "Execute a semantic similarity search using dense vector embeddings.\n\nThis endpoint retrieves items by meaning rather than exact keyword matching. It supports two modes:\n\n**Text Mode**:\n- Provide a text string (minimum 5 characters)\n- The server generates a 768-dimensional embedding using the multilingual-e5-small model\n- Results are ranked by cosine similarity to the generated embedding\n\n**Vector Mode**:\n- Provide a pre-computed 768-dimensional vector\n- Useful when you have embeddings from another source or want to cache/reuse them\n- Results are ranked by cosine similarity to your provided vector\n\nYou must provide either `text` OR `vector`, but not both.\n\n**Result Ordering**:\nResults are ordered by similarity score (highest first). Scores represent cosine similarity between the query and document vectors, ranging from 0.0 to 1.0 where 1.0 is identical.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticRequest" }, "examples": { "text_search": { "summary": "Search by text", "value": { "index": "polymarket-items", "text": "machine learning and artificial intelligence advancements", "size": 20 } }, "vector_search": { "summary": "Search by pre-computed 768-dim vector (truncated for readability)", "value": { "index": "polymarket-items", "vector": "Array of 768 floating-point numbers (e.g., [0.1, -0.2, 0.3, ...])", "size": 15 } }, "text_with_fields": { "summary": "Text search returning specific fields", "value": { "index": "polymarket-items", "text": "political prediction markets", "size": 25, "select_fields": [ "item_id", "title", "liquidity", "volume_24hr" ] } } } } } }, "responses": { "200": { "description": "Successful semantic search result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { "success": { "summary": "Successful semantic search result", "value": { "query": { "knn": { "field": "text_vector", "k": 20, "num_candidates": 200, "query_vector_builder": { "text_embedding": { "model_id": ".multilingual-e5-small", "model_text": "machine learning" } } } }, "result": { "took_es": 150, "took_es_roundtrip": 165, "total_hits": 4567, "max_score": 0.95, "hits": [ { "_index": "polymarket-items", "_id": "98765", "_score": 0.95, "_source": { "item_id": "item_789", "text": "Breakthrough in machine learning models", "score_popular": 0.72 } } ] }, "error": null } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Console API key. Use `Bearer mbd-{your-api-key}`." } }, "schemas": { "SemanticRequest": { "type": "object", "required": [ "index" ], "description": "Request payload for the Semantic Search endpoint. Enables semantic similarity search using dense vector embeddings.\n\n**Text Mode**: Provide a text string (minimum 5 characters). The server generates embeddings using the multilingual-e5-small model (768 dimensions). Results are ranked by cosine similarity.\n\n**Vector Mode**: Provide a pre-computed 768-dimensional vector. Useful when you already have embeddings. Results are ranked by cosine similarity.\n\nYou must provide either `text` OR `vector`, but not both.\n", "properties": { "index": { "type": "string", "description": "The Elasticsearch index to search", "enum": [ "polymarket-items", "polymarket-items", "polymarket-wallets", "token-items", "kalshi-notifications" ], "example": "polymarket-items" }, "text": { "type": "string", "description": "Text query for semantic search. Minimum 5 characters. Cannot be used together with `vector`.", "minLength": 5, "example": "machine learning and AI advancements" }, "vector": { "type": "array", "description": "Pre-computed embedding vector. Must be exactly 768 dimensions (matching multilingual-e5-small model output). Cannot be used together with `text`.", "items": { "type": "number" }, "minItems": 768, "maxItems": 768 }, "size": { "type": "integer", "description": "Number of results to return", "default": 100, "minimum": 1, "maximum": 10000, "example": 20 }, "only_ids": { "type": "boolean", "description": "Return only document IDs without source data. Mutually exclusive with `select_fields` and `include_vector`.", "default": false }, "select_fields": { "type": "array", "description": "Specific fields to return in results. Mutually exclusive with `only_ids` and `include_vector`.", "items": { "type": "string" }, "example": [ "item_id", "text", "score_popular" ] }, "include_vector": { "type": "boolean", "description": "Include vector embeddings in the response. Mutually exclusive with `only_ids` and `select_fields`.", "default": false } } }, "SearchResponse": { "type": "object", "description": "Response from search endpoints containing the executed query, results, and timing metrics.", "properties": { "query": { "type": "object", "description": "The Elasticsearch query that was executed (useful for debugging)", "additionalProperties": true }, "result": { "type": "object", "nullable": true, "description": "Search results from Elasticsearch", "properties": { "took_es": { "type": "integer", "description": "Elasticsearch query execution time in milliseconds", "example": 45 }, "took_es_roundtrip": { "type": "integer", "description": "Total roundtrip time including network in milliseconds", "example": 52 }, "total_hits": { "type": "integer", "description": "Total number of matching documents", "example": 1234 }, "max_score": { "type": "number", "description": "Maximum relevance score among results", "example": 2.5 }, "hits": { "type": "array", "description": "Array of matching documents", "items": { "type": "object", "properties": { "_index": { "type": "string", "description": "Elasticsearch index name" }, "_id": { "type": "string", "description": "Document ID" }, "_score": { "type": "number", "description": "Relevance score" }, "_source": { "type": "object", "description": "Document fields and values", "additionalProperties": true } } } } } }, "error": { "type": "string", "nullable": true, "description": "Error message if the query failed", "example": null } } }, "ErrorResponse": { "type": "object", "description": "Error response returned for 400/401 status codes.", "properties": { "detail": { "type": "string", "description": "Error details", "example": "Invalid filter type specified" } } } } } } ```