This document provides comprehensive documentation for the Lilith Content Service Search API, powered by Elasticsearch, including full-text search, faceted search, autocomplete, and analytics.
Overview#
The Content Search API enables powerful search capabilities across all content types:
- Full-Text Search: Multi-field search with boosting and highlighting
- Faceted Search: Aggregations for filtering and navigation
- Autocomplete: Real-time suggestions using edge-ngram tokenization
- Search Analytics: Query tracking, click-through rates, and insights
- Indexing: Single and bulk content indexing with admin endpoints
Table of Contents#
Content Types#
Searchable Content Types#
| Type | Description |
|---|---|
lesson |
Course lessons |
meditation |
Meditation content |
persona |
AI personas |
course |
Full courses |
wisdom |
Wisdom teachings |
Sort Fields#
| Field | Description |
|---|---|
relevance |
Search relevance score (default) |
created_at |
Creation date |
updated_at |
Last update date |
published_at |
Publication date |
popularity |
Popularity score |
rating |
Average rating |
title |
Alphabetical by title |
Boost Configuration#
Default field boosting for relevance scoring:
| Field | Boost Factor |
|---|---|
title |
3.0x |
tags |
2.0x |
description |
1.5x |
rating |
1.3x |
recency |
1.2x |
popularity |
1.1x |
content |
1.0x |
Search Endpoints#
Full-Text Search (GET)#
Perform full-text search with query parameters.
Endpoint: GET /v1/search
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
q |
string | Search query |
types |
string | Comma-separated content types |
status |
string | Comma-separated statuses |
tags |
string | Comma-separated tags |
categories |
string | Comma-separated categories |
traditions |
string | Comma-separated traditions |
difficulty |
string | Comma-separated difficulty levels |
minDuration |
integer | Minimum duration in minutes |
maxDuration |
integer | Maximum duration in minutes |
minRating |
number | Minimum average rating |
isPremium |
boolean | Filter premium content |
isFree |
boolean | Filter free content |
locale |
string | Content locale |
personaType |
string | Comma-separated persona types |
instructorId |
uuid | Filter by instructor |
knowledgeAreas |
string | Comma-separated knowledge areas |
from |
integer | Pagination offset (default: 0) |
size |
integer | Results per page (max: 100, default: 20) |
sortBy |
string | Sort field |
sortOrder |
string | asc or desc |
highlight |
boolean | Enable highlighting (default: true) |
fuzzy |
boolean | Enable fuzzy matching (default: false) |
Request:
curl -X GET "https://api.lilith.app/v1/search?q=meditation&types=lesson,meditation&difficulty=beginner&size=10" \
-H "Authorization: Bearer <access_token>"
Response:
{
"hits": [
{
"id": "content_123",
"contentType": "meditation",
"score": 12.5,
"document": {
"id": "content_123",
"contentType": "meditation",
"slug": "morning-meditation",
"title": "Morning Meditation",
"description": "Start your day with peace",
"tags": ["morning", "beginner"],
"categories": ["mindfulness"],
"status": "published",
"locale": "en",
"durationMinutes": 10,
"difficulty": "beginner",
"isPremium": false,
"popularity": 85,
"averageRating": 4.7,
"ratingCount": 120
},
"highlights": {
"title": ["Morning <em>Meditation</em>"],
"description": ["peaceful <em>meditation</em> practice"]
}
}
],
"total": 42,
"maxScore": 12.5,
"facets": {
"contentTypes": [
{ "key": "meditation", "count": 25 },
{ "key": "lesson", "count": 17 }
],
"difficulty": [
{ "key": "beginner", "count": 30 },
{ "key": "intermediate", "count": 10 },
{ "key": "advanced", "count": 2 }
],
"tags": [
{ "key": "morning", "count": 15 },
{ "key": "breathing", "count": 12 }
]
},
"took": 15,
"from": 0,
"size": 10
}
Full-Text Search (POST)#
Search with a request body for complex queries.
Endpoint: POST /v1/search
Request Body:
{
"query": "meditation mindfulness",
"contentTypes": ["meditation", "lesson"],
"status": ["published"],
"tags": ["beginner"],
"difficulty": ["beginner", "intermediate"],
"minDuration": 5,
"maxDuration": 30,
"minRating": 4.0,
"isPremium": false,
"locale": "en",
"from": 0,
"size": 20,
"sortBy": "relevance",
"sortOrder": "desc",
"highlight": true,
"fuzzy": true
}
Request:
curl -X POST "https://api.lilith.app/v1/search" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"query": "meditation",
"contentTypes": ["meditation"],
"difficulty": ["beginner"],
"size": 10
}'
Facets Response Structure#
The search response includes faceted navigation data:
{
"facets": {
"contentTypes": [{ "key": "meditation", "count": 25 }],
"tags": [{ "key": "morning", "count": 15 }],
"categories": [{ "key": "mindfulness", "count": 20 }],
"traditions": [{ "key": "zen", "count": 8 }],
"difficulty": [{ "key": "beginner", "count": 30 }],
"status": [{ "key": "published", "count": 42 }],
"personaTypes": [{ "key": "guide", "count": 5 }],
"knowledgeAreas": [{ "key": "meditation", "count": 15 }],
"durationRanges": [{ "key": "5-10", "count": 12 }],
"ratingRanges": [{ "key": "4-5", "count": 25 }]
}
}
Autocomplete#
Get Suggestions#
Get autocomplete suggestions as the user types.
Endpoint: GET /v1/search/autocomplete
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
prefix |
string | Yes | Search prefix |
types |
string | No | Comma-separated content types |
field |
string | No | Field to search: title, tags, all (default: all) |
size |
integer | No | Max suggestions (default: 10) |
fuzzy |
boolean | No | Enable fuzzy matching |
Request:
curl -X GET "https://api.lilith.app/v1/search/autocomplete?prefix=med&types=meditation&size=5" \
-H "Authorization: Bearer <access_token>"
Response:
{
"suggestions": [
{
"text": "meditation",
"score": 15.2,
"contentType": "meditation",
"id": "content_123"
},
{
"text": "meditation techniques",
"score": 12.8
},
{
"text": "meditative breathing",
"score": 10.5
}
],
"took": 5
}
Search Analytics#
Record Click Event#
Track when a user clicks on a search result.
Endpoint: POST /v1/search/click
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | Search query that led to click |
contentId |
string | Yes | Clicked content ID |
contentType |
string | Yes | Content type |
position |
integer | Yes | Result position (0-indexed) |
userId |
string | No | User ID |
Request:
curl -X POST "https://api.lilith.app/v1/search/click" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"query": "meditation beginner",
"contentId": "content_123",
"contentType": "meditation",
"position": 2,
"userId": "user_456"
}'
Response:
{ "success": true }
Get Analytics Summary#
Retrieve search analytics for a date range.
Endpoint: GET /v1/search/analytics
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate |
string | Yes | Start date (ISO 8601) |
endDate |
string | Yes | End date (ISO 8601) |
eventType |
string | No | Filter by event type: search, click, impression, conversion |
userId |
string | No | Filter by user |
contentType |
string | No | Filter by content type |
Request:
curl -X GET "https://api.lilith.app/v1/search/analytics?startDate=2024-01-01&endDate=2024-01-31" \
-H "Authorization: Bearer <access_token>"
Response:
{
"totalSearches": 15000,
"uniqueQueries": 3500,
"averageResultCount": 25.3,
"zeroResultQueries": 120,
"averageLatencyMs": 45,
"clickThroughRate": 0.35,
"topQueries": [
{ "query": "meditation", "count": 500 },
{ "query": "beginner yoga", "count": 350 },
{ "query": "stress relief", "count": 280 }
],
"topClickedContent": [
{ "contentId": "content_123", "contentType": "meditation", "clicks": 250 },
{ "contentId": "content_456", "contentType": "lesson", "clicks": 180 }
],
"searchesByContentType": {
"meditation": 6000,
"lesson": 4500,
"course": 2500,
"persona": 1500,
"wisdom": 500
},
"period": {
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-01-31T23:59:59.999Z"
}
}
Indexing (Admin)#
Index Single Content#
Index a single content item.
Endpoint: POST /v1/search/index
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Content ID |
contentType |
string | Yes | Content type |
slug |
string | Yes | URL slug |
title |
string | Yes | Title |
description |
string | No | Description |
content |
string | No | Full content |
tags |
string[] | No | Tags |
categories |
string[] | No | Categories |
status |
string | No | Status (default: draft) |
locale |
string | No | Locale (default: en) |
availableLocales |
string[] | No | Available locales |
isPremium |
boolean | No | Premium flag |
isFree |
boolean | No | Free flag |
durationMinutes |
integer | No | Duration |
difficulty |
string | No | Difficulty |
tradition |
string | No | Tradition |
type |
string | No | Subtype |
focus |
string | No | Focus area |
personaType |
string | No | Persona type |
instructorId |
string | No | Instructor ID |
instructorName |
string | No | Instructor name |
knowledgeAreas |
string[] | No | Knowledge areas |
teachingMethods |
string[] | No | Teaching methods |
popularity |
number | No | Popularity score |
averageRating |
number | No | Average rating |
ratingCount |
integer | No | Rating count |
Request:
curl -X POST "https://api.lilith.app/v1/search/index" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"id": "meditation_123",
"contentType": "meditation",
"slug": "morning-calm",
"title": "Morning Calm Meditation",
"description": "Start your day with peace",
"tags": ["morning", "calm", "beginner"],
"status": "published",
"durationMinutes": 10,
"difficulty": "beginner"
}'
Response (201 Created):
{ "success": true, "id": "meditation_123" }
Bulk Index Content#
Index multiple content items at once.
Endpoint: POST /v1/search/index/bulk
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
items |
array | Yes | Array of content items (max: 1000) |
Request:
curl -X POST "https://api.lilith.app/v1/search/index/bulk" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"id": "meditation_1",
"contentType": "meditation",
"slug": "morning-calm",
"title": "Morning Calm"
},
{
"id": "meditation_2",
"contentType": "meditation",
"slug": "evening-peace",
"title": "Evening Peace"
}
]
}'
Response:
{
"success": 2,
"failed": 0,
"errors": [],
"took": 150
}
Remove from Index#
Remove content from the search index.
Endpoint: DELETE /v1/search/index/:contentType/:id
Request:
curl -X DELETE "https://api.lilith.app/v1/search/index/meditation/meditation_123" \
-H "Authorization: Bearer <access_token>"
Response: 204 No Content
Update Popularity#
Update a content item's popularity score.
Endpoint: PUT /v1/search/index/:id/popularity
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
popularity |
number | Yes | New popularity score (0+) |
Request:
curl -X PUT "https://api.lilith.app/v1/search/index/meditation_123/popularity" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "popularity": 95.5 }'
Update Rating#
Update a content item's rating information.
Endpoint: PUT /v1/search/index/:id/rating
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
averageRating |
number | Yes | Average rating (0-5) |
ratingCount |
integer | Yes | Total rating count |
Request:
curl -X PUT "https://api.lilith.app/v1/search/index/meditation_123/rating" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "averageRating": 4.8, "ratingCount": 150 }'
Error Handling#
Error Codes#
| Code | HTTP Status | Description |
|---|---|---|
SEARCH_ERROR |
500 | Search operation failed |
INVALID_REQUEST |
400 | Invalid request parameters |
NOT_FOUND |
404 | Content not found in index |
Example Error Response#
{
"code": "INVALID_REQUEST",
"message": "startDate and endDate query parameters are required"
}
SDK Integration#
TypeScript/JavaScript#
import { LilithClient } from '@lilith/sdk';
const client = new LilithClient({
apiKey: process.env.LILITH_API_KEY,
});
// Full-text search
const results = await client.search.search({
query: 'meditation mindfulness',
contentTypes: ['meditation', 'lesson'],
difficulty: ['beginner'],
size: 10,
});
console.log(`Found ${results.total} results`);
results.hits.forEach((hit) => {
console.log(`${hit.document.title} (score: ${hit.score})`);
});
// Autocomplete
const suggestions = await client.search.autocomplete({
prefix: 'med',
size: 5,
});
// Record click
await client.search.recordClick({
query: 'meditation',
contentId: 'content_123',
contentType: 'meditation',
position: 2,
});
// Get analytics
const analytics = await client.search.getAnalytics({
startDate: '2024-01-01',
endDate: '2024-01-31',
});
console.log(`CTR: ${(analytics.clickThroughRate * 100).toFixed(1)}%`);
// Index content (admin)
await client.search.index({
id: 'meditation_123',
contentType: 'meditation',
slug: 'morning-calm',
title: 'Morning Calm Meditation',
});
Related Documentation#
- Lesson API - Course lesson management
- Meditation API - Meditation content management
- Recommendation API - Content recommendations
- Authentication - API authentication
Questions?#
- Technical Support: api-support@lilith.app
- Documentation: GitHub Issues