Documentation Index
Fetch the complete documentation index at: https://podium.build/docs/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Podium provides multiple search and discovery surfaces powered by PostgreSQL tsvector full-text search with custom ranking. The search system spans products, creators, campaigns, rewards, and collectibles with both traditional keyword search and AI-enhanced universal search.
Full-Text Search
Entity Search
curl "https://api.podium.build/api/v1/search?query=hyaluronic+serum&type=product&limit=20&page=1" \
-H "Authorization: Bearer $PODIUM_API_KEY"
Query Parameters
| Param | Type | Required | Description |
|---|
query | string | Yes | Search query |
type | enum | No | campaign, creator, user, product, or reward |
orderBy | string | No | Sort order |
page | integer | No | Page number (1-indexed) |
limit | integer | No | Results per page |
type is omitted, the search returns results across all entity types, grouped by category.
Response
{
"data": [
{
"type": "product",
"id": "clprod_abc123",
"name": "Hyaluronic Acid Serum",
"slug": "hyaluronic-acid-serum",
"description": "Lightweight hydrating serum...",
"creatorSlug": "clean-beauty-co",
"price": 2900,
"imageUrl": "https://cdn.example.com/product.jpg",
"score": 0.892
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 8
}
}
Universal Search
Universal search provides a unified search experience with optional LLM-powered synthesis that generates natural-language answers alongside traditional results.
curl "https://api.podium.build/api/v1/universal-search?query=best+moisturizer+for+dry+skin&entityTypes=product,campaign&llmMode=auto&limit=10" \
-H "Authorization: Bearer $PODIUM_API_KEY"
Query Parameters
| Param | Type | Required | Description |
|---|
query | string | Yes | Search query |
entityTypes | string | No | Comma-separated: product, campaign, creator |
page | integer | No | Page number |
limit | integer | No | Results per page |
llm | boolean | No | Enable LLM synthesis |
llmMode | enum | No | auto, force, or off — controls when LLM is invoked |
answer | boolean | No | Include LLM-generated answer |
includeSuggestions | boolean | No | Include search suggestions |
LLM Modes
| Mode | Behavior |
|---|
auto | LLM is invoked when the query appears conversational or complex |
force | Always invoke LLM synthesis |
off | Traditional search only (default) |
Response with LLM Synthesis
{
"results": [
{
"type": "product",
"id": "clprod_abc",
"name": "Ultra Hydrating Cream",
"score": 0.95
}
],
"answer": "For dry skin, look for moisturizers with hyaluronic acid and ceramides. Clean Beauty Co's Ultra Hydrating Cream is a top pick with its triple-layer moisture barrier technology.",
"suggestions": ["ceramide cream", "barrier repair", "overnight mask"]
}
Search Suggestions
curl "https://api.podium.build/api/v1/universal-search/suggestions?query=hya&limit=5" \
-H "Authorization: Bearer $PODIUM_API_KEY"
| Param | Type | Default | Description |
|---|
query | string | — | Partial query for suggestions |
limit | integer | 10 | Max suggestions (max: 50) |
{
"suggestions": [
"hyaluronic acid serum",
"hyaluronic moisturizer",
"hydrating face mask"
]
}
Autocomplete
Legacy autocomplete endpoint for backward compatibility:
curl "https://api.podium.build/api/v1/autocomplete?query=clea&limit=10" \
-H "Authorization: Bearer $PODIUM_API_KEY"
| Param | Type | Default | Description |
|---|
query | string | — | Partial query |
limit | integer | 10 | Max results |
/universal-search/suggestions for new integrations.
Discovery Feeds
Curated content surfaces for browsing.
Main Discovery
curl "https://api.podium.build/api/v1/discover?suggested=true&page=1&limit=20" \
-H "Authorization: Bearer $PODIUM_API_KEY"
| Param | Type | Description |
|---|
userId | string | Personalize for this user |
suggested | boolean | Include editorial suggestions |
page | integer | Page number |
limit | integer | Results per page |
Category-Specific Discovery
| Endpoint | Returns |
|---|
/discover/campaigns | Active discoverable campaigns |
/discover/collectibles | Discoverable on-chain collectibles |
/discover/creators | Featured creators |
Personalized Feeds
For-You Feed
Returns a personalized product feed based on the user’s intent profile, interactions, and enrichment data. This is the consumer-facing expression of the agentic product feed.
curl "https://api.podium.build/api/v1/for-you/feed?userId=clxyz1234567890&page=1" \
-H "Authorization: Bearer $PODIUM_API_KEY"
| Param | Type | Required | Description |
|---|
userId | string | Yes | User to personalize for |
interests | string | No | JSON array of interest overrides |
page | integer | No | Page number |
Recommended Creators
curl "https://api.podium.build/api/v1/for-you/creators?userId=clxyz1234567890" \
-H "Authorization: Bearer $PODIUM_API_KEY"
Saved Items (Wishlist)
Users can save items for later across three entity types.
Save an Item
curl -X POST https://api.podium.build/api/v1/saved-item \
-H "Authorization: Bearer $PODIUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userId": "clxyz1234567890",
"itemType": "PRODUCT",
"itemId": "clprod_abc123"
}'
List Saved Items
curl "https://api.podium.build/api/v1/saved-item?userId=clxyz1234567890" \
-H "Authorization: Bearer $PODIUM_API_KEY"
Remove Saved Item
curl -X DELETE https://api.podium.build/api/v1/saved-item/clsaved_abc \
-H "Authorization: Bearer $PODIUM_API_KEY"
Supported Item Types
| Type | Description |
|---|
PRODUCT | Saved product |
CAMPAIGN | Saved campaign |
REWARD | Saved reward |
Search Architecture
Search uses PostgreSQL’s built-in full-text search with tsvector columns on SearchDoc and SearchChunk models. Documents are indexed with custom ranking weights for relevance ordering.
Products published via the product-published event are automatically indexed. Campaign and creator records are indexed on creation and update.
The universal search layer adds optional AI synthesis to generate conversational answers grounded in the search results.
Endpoint Summary
| Method | Path | Description |
|---|
GET | /search | Full-text search (by entity type) |
GET | /autocomplete | Legacy autocomplete |
GET | /universal-search | Unified search with optional AI synthesis |
GET | /universal-search/suggestions | Search suggestions |
GET | /discover | Curated discovery feed |
GET | /discover/campaigns | Discoverable campaigns |
GET | /discover/collectibles | Discoverable collectibles |
GET | /discover/creators | Discoverable creators |
GET | /for-you/feed | Personalized feed |
GET | /for-you/creators | Recommended creators |
POST | /saved-item | Save an item |
GET | /saved-item | List saved items |
DELETE | /saved-item/{id} | Remove saved item |
