# ❜embed - The AI Recommendation System for Web3 Documentation

> ❜embed's documentation is your one-stop resource for quickly learning and integrating our AI-powered tools. You’ll find: 	•	Quickstart Guides: Step-by-step tutorials for rendering feeds with the Embed SDK and building Farcaster mini-apps in React. 	•	API Reference: Complete OpenAPI specs for content discovery, moderation, labeling, and semantic search endpoints, with request & response examples. 	•	Deep-Dive Tutorials: Hands-on walkthroughs for RAG implementations, custom AI-agent development, and best practices for training on your own label taxonomies. 	•	Recipes & Code Samples: Ready-to-use snippets in JavaScript, Python, and more—perfect for prototyping and production. 	•	Community & Support: Links to FAQ pages, our Developer Slack, Farcaster, and X channels for real-time help and discussion.

## Guides
- [guide-api-overview](https://docs.getembed.ai/docs/guide-api-overview.md)
- [guide-authentication](https://docs.getembed.ai/docs/guide-authentication.md)
- [quickstart-studio-sdk](https://docs.getembed.ai/docs/quickstart-studio-sdk.md)
- [glossary](https://docs.getembed.ai/docs/glossary.md)
- [vibecoding-with-embed](https://docs.getembed.ai/docs/vibecoding-with-embed.md)
- [Essentials - What Makes a Good Feed?](https://docs.getembed.ai/docs/what-makes-a-good-feed.md): Learn how to build a useful feed in Console with source selection, search, filtering, hydration, preview, and feed deployment.
- [platform-coverage](https://docs.getembed.ai/docs/platform-coverage.md)
- [data-sources](https://docs.getembed.ai/docs/data-sources.md)
- [Supported Indices](https://docs.getembed.ai/docs/supported-indices.md): Search indices available in the Console algorithm Search tab.
- [Building Algorithms](https://docs.getembed.ai/docs/guide-building-algorithms.md): Build feed and notification algorithms in Console with Search, Hydration, and DSL.
- [algorithm-dsl-functions](https://docs.getembed.ai/docs/algorithm-dsl-functions.md)
- [search](https://docs.getembed.ai/docs/search.md)
- [algo-filter-cookbook](https://docs.getembed.ai/docs/algo-filter-cookbook.md)
- [Validate & Test](https://docs.getembed.ai/docs/validate-and-test.md)
- [Feed Management](https://docs.getembed.ai/docs/guide-feed-management.md): Manage production feeds in Console with saved algorithms, feed configs, fallbacks, cache settings, and test runs.
- [feeds-dsl-functions](https://docs.getembed.ai/docs/feeds-dsl-functions.md)
- [Deploy Feed Configs](https://docs.getembed.ai/docs/deploy-feed-configs.md): Deploy saved algorithms as production feed configs in Console.
- [Serving Feeds in Production](https://docs.getembed.ai/docs/deploy-serving.md)
- [Feed deployment status](https://docs.getembed.ai/docs/deploy-status.md)
- [Notifications](https://docs.getembed.ai/docs/guide-notifications.md): Build notification products in Console with algorithms, notification configs, webhooks, cooldowns, and budgets.
- [notifications-dsl-functions](https://docs.getembed.ai/docs/notifications-dsl-functions.md)
- [Building Notification Streams](https://docs.getembed.ai/docs/building-notification-streams.md): Build notification streams from saved algorithms and notification configs.

## API Reference
- [Data Ingestion](https://docs.getembed.ai/reference/data-ingestion.md)
- [Create a new datasource](https://docs.getembed.ai/reference/createdatasource.md): Creates a new datasource with automatic Embed stream provisioning
- [Ingest item data](https://docs.getembed.ai/reference/ingestitems.md): Ingest content items (posts, articles, videos, etc.) from various protocols
- [Ingest user data](https://docs.getembed.ai/reference/ingestusers.md): Ingest user profile data from various protocols
- [Track item interactions](https://docs.getembed.ai/reference/trackiteminteractions.md): Track user interactions with content items
- [Track user interactions](https://docs.getembed.ai/reference/trackuserinteractions.md): Track user interactions (uses same schema as item interactions but routes to different stream)
- [Compose algorithm from prompt](https://docs.getembed.ai/reference/algocompose.md): Generate a feed algorithm from a natural language prompt using an AI agent. The agent has access to DS services (search, stories, features, scoring, ranking) to explore data and compose the algorithm.  Optionally pass `farcaster_fid` or `polymarket_wallet` so the agent can explore with real user context.
- [Get help from AI assistant](https://docs.getembed.ai/reference/algohelp.md): Get contextual help from an AI assistant for the embed feed builder. Pass a conversation (single string or array of messages) and optional context (e.g. product, page, source).
- [Validate algorithm](https://docs.getembed.ai/reference/algovalidate.md): Validate a feed algorithm without executing it. Runs two checks:  - **Syntax**: Validates algorithm code against the algo-dsl spec (version can be specified via `version` field, defaults to `V1`). - **Security**: Ensures the algorithm does not use disallowed APIs or override MBD behavior.  Returns a **signature** when both checks pass. This signature is required to run the algorithm via `/run/algo` or save it via `/deploy/algos`.
- [Create algorithm](https://docs.getembed.ai/reference/createfeedalgo.md): Create a new algorithm. The `account_id` in the payload must match the authenticated account. The `signature` field is obtained from `/algo/validate` after passing both syntax and security checks.
- [Delete algorithm](https://docs.getembed.ai/reference/deletefeedalgo.md): Soft-delete a algorithm (sets `deleted_at`). Only allowed if the algo belongs to your account.
- [Get algorithm by ID](https://docs.getembed.ai/reference/getfeedalgo.md): Retrieve a algorithm by its ID. Allowed if the algo belongs to your account or is public.
- [List algorithms](https://docs.getembed.ai/reference/listfeedalgos.md): List algorithms accessible to the account (owned + public from others). Returns own algos and public algos from other accounts (read-only access to public).
- [Update algorithm](https://docs.getembed.ai/reference/updatefeedalgo.md): Update a algorithm. Only allowed if the algo belongs to your account. All fields are optional — only provided fields are updated.
- [Run a signed algorithm](https://docs.getembed.ai/reference/feedbuilderrun.md): Execute a signed feed algorithm in a sandbox with a 10-second timeout. Requires the algorithm code and a signature from /algo/validate.
- [Create config](https://docs.getembed.ai/reference/createfeedconfig.md): Create a new deployment configuration. The `account_id` in the payload must match the authenticated account. The `feed_config` object defines which algorithms to use, fallback chains, cache settings, and page size.
- [Delete config](https://docs.getembed.ai/reference/deletefeedconfig.md): Soft-delete a config (sets `deleted_at`). Only allowed if the config belongs to your account.
- [Get config by ID](https://docs.getembed.ai/reference/getfeedconfig.md): Retrieve a config by its ID. Allowed if the config belongs to your account or is public.
- [List configs](https://docs.getembed.ai/reference/listfeedconfigs.md): List configs accessible to the account (owned + public from others).
- [Update config](https://docs.getembed.ai/reference/updatefeedconfig.md): Update a config. Only allowed if the config belongs to your account. All fields are optional — only provided fields are updated.
- [Serve feed by config ID](https://docs.getembed.ai/reference/deployserve.md): Serves a merged feed using a saved config from the database by ID. Returns the first page of feed items and a `served_id` for pagination via `/deploy/serve/page` and new-items detection via `/deploy/serve/new_items`.  The config defines which algorithms to run, fallback chains, cache TTLs, and page size. Items from multiple algorithms are interleaved based on configured weights.
- [Get feed page](https://docs.getembed.ai/reference/deployservepage.md): Get a paginated page of feed items. Use the `served_id` returned from `POST /deploy/serve` or `POST /deploy/preview`.  Pages are 1-based. The total number of pages is returned in the initial serve response as `num_pages`.
- [Get new items since last view](https://docs.getembed.ai/reference/deployservenewitems.md): Returns items that are new since the previous feed version. Use the `served_id` from `POST /deploy/serve` or `POST /deploy/preview`.  This is useful for showing a "new items available" indicator in your UI without re-fetching the entire feed.
- [Preview feed with inline config](https://docs.getembed.ai/reference/deploypreview.md): Serves a merged feed from main feeds and fallbacks per the provided deployment config. Use this to test a config before saving it.  Returns the first page of feed items and a `served_id` for pagination via `/deploy/serve/page` and new-items detection via `/deploy/serve/new_items`. Same response format as `/deploy/serve`.
- [Clear feed cache](https://docs.getembed.ai/reference/deploycacheclear.md): Clears cached version entries for feed algos the user can access (owned or public). Use when you've updated an algorithm and need to force a fresh build.  Pass an array of algorithm IDs to clear. Optionally include user inputs if the cached feed was built with user context.
- [List Frequent Values](https://docs.getembed.ai/reference/listfrequentvalues.md): Retrieve the most frequently occurring values for a specific field in an index.  This endpoint is useful for discovering popular values in a field before building filters or queries. Common use cases include: - Discovering popular languages (`lang` field) - Finding trending channels/topics (`channels` field) - Identifying common AI labels (`ai_labels_med`, `ai_labels_high` fields) - Exploring active features of any keyword field  **Data Scope**: Results are based on data from the last 7 days. This ensures you get recently relevant values rather than historical ones. The exact date field used varies by index: - `polymarket-trades`: `item_creation_timestamp` - `polymarket-items`: `created_at` - `polymarket-wallets`: `updated_at` - `token-items`: `zora_updated_at` - `kalshi-notifications`: `updated_at` - `polymarket-wallets`: `updated_at` - `token-items`: `last_updated`  Results are sorted by frequency (highest first) and limited to the requested size (default 100).
- [Boost](https://docs.getembed.ai/reference/searchboost.md): Execute a search query with filtering, exclusion, and result boosting against Elasticsearch indices.  This endpoint extends filter-and-sort by adding a `boost` array for soft relevance tuning. Boost filters act as SHOULD clauses — they increase the relevance score of matching documents without strictly filtering them out.  **Filter Logic**: - `include` array: must-match filters (AND logic), identical to Filter and Sort. - `exclude` array: must-not filters (NOT logic), identical to Filter and Sort. - `boost` array: SHOULD directives (OR logic) with configurable boost multipliers. A document can match zero or more boost filters; matching multiple boosts stacks their effects.  **Boost Values**: - `1.0` = no effect on score - `> 1.0` = increase score (e.g., `2.0` doubles the relevance contribution) - `< 1.0` = decrease score  **Sorting Note**: The boost endpoint does **not** support `sort_by`. Results are ordered by relevance score (highest first), which incorporates both the base Elasticsearch score and any boost multipliers.
- [Filter and Sort](https://docs.getembed.ai/reference/searchfilterandsort.md): Execute a search query with filtering and sorting capabilities against Elasticsearch indices.  This endpoint is the primary structured search method. Use it when you need exact-match filters, range queries, and field-based ordering.  **Filter Logic**: - `include` array: filters that must ALL match (AND logic). A document must satisfy every filter to be included. - `exclude` array: filters that must NOT match (NOT logic). A document matching any exclude filter is removed. - Combined: `(include[0] AND include[1] AND ...) AND NOT (exclude[0] OR exclude[1] OR ...)`  **Sorting**: The `sort_by` parameter orders results by a numeric or date field. Without `sort_by`, results are ordered by Elasticsearch relevance score.  **Available Indices**: - `polymarket-trades` — Social posts from the Farcaster protocol - `polymarket-items` — Prediction market contracts from Polymarket - `polymarket-wallets` — User wallets and profiles from Polymarket - `token-items` — Creator coins from the Zora platform - `kalshi-notifications` — Prediction market contracts from Kalshi (via DFlow on Solana) - `polymarket-wallets` — User wallets and profiles from Kalshi - `token-items` — Multi-chain token data (Base, Ethereum, Solana)  Refer to the Filter schema for the complete list of available filter types and per-index field mappings.
- [Semantic Search](https://docs.getembed.ai/reference/searchsemantic.md): 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.
- [Generate](https://docs.getembed.ai/reference/generatestories.md): Generate personalized onchain stories about market activity, significant bets, and price movements.  This endpoint creates narrative-driven content about Polymarket activity tailored to a specific user's wallet and interests. Stories are generated from multiple data sources:  **Story Types**: - **New Markets** (`new_market`): Recently created prediction markets relevant to the user - **Significant Bets** (`user_markets_bets`, `relevant_markets_bets`, `bet`): Large bets on markets the user participates in or related markets discovered via graph analysis - **Price Changes** (`price_change`): Markets experiencing significant price movements, with optional AI-generated commentary explaining the change - **Relevant Markets** (`relevant_market`): Markets related to user's activity without recent bet or price activity  **Engines**: - **polymarket_v1**: Multi-source, modular story generation with granular control over each story type. Configure time windows, minimum bet amounts, and result counts independently for each source. - **polymarket_v2**: Simplified, unified approach combining all signals into a single ranked story feed. Just specify `num_stories` and `new_market_hours`.  **Data Sources**: - Elasticsearch: Market metadata, price changes, new markets - Neo4j: Bet graph, user relationships, market connections - DynamoDB: Market details, bet history, price change events