Skip to main content

​
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

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

ParamTypeRequiredDescription
querystringYesSearch query
typeenumNocampaign, creator, user, product, or reward
orderBystringNoSort order
pageintegerNoPage number (1-indexed)
limitintegerNoResults per page
When 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 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

ParamTypeRequiredDescription
querystringYesSearch query
entityTypesstringNoComma-separated: product, campaign, creator
pageintegerNoPage number
limitintegerNoResults per page
llmbooleanNoEnable LLM synthesis
llmModeenumNoauto, force, or off — controls when LLM is invoked
answerbooleanNoInclude LLM-generated answer
includeSuggestionsbooleanNoInclude search suggestions

​
LLM Modes

ModeBehavior
autoLLM is invoked when the query appears conversational or complex
forceAlways invoke LLM synthesis
offTraditional 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"
ParamTypeDefaultDescription
querystring—Partial query for suggestions
limitinteger10Max 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"
ParamTypeDefaultDescription
querystring—Partial query
limitinteger10Max results
Prefer /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"
ParamTypeDescription
userIdstringPersonalize for this user
suggestedbooleanInclude editorial suggestions
pageintegerPage number
limitintegerResults per page

​
Category-Specific Discovery

EndpointReturns
/discover/campaignsActive discoverable campaigns
/discover/collectiblesDiscoverable on-chain collectibles
/discover/creatorsFeatured 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"
ParamTypeRequiredDescription
userIdstringYesUser to personalize for
interestsstringNoJSON array of interest overrides
pageintegerNoPage number
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

TypeDescription
PRODUCTSaved product
CAMPAIGNSaved campaign
REWARDSaved 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

MethodPathDescription
GET/searchFull-text search (by entity type)
GET/autocompleteLegacy autocomplete
GET/universal-searchUnified search with optional AI synthesis
GET/universal-search/suggestionsSearch suggestions
GET/discoverCurated discovery feed
GET/discover/campaignsDiscoverable campaigns
GET/discover/collectiblesDiscoverable collectibles
GET/discover/creatorsDiscoverable creators
GET/for-you/feedPersonalized feed
GET/for-you/creatorsRecommended creators
POST/saved-itemSave an item
GET/saved-itemList saved items
DELETE/saved-item/{id}Remove saved item