Eve library

Content Search API

Guide

Revision 1

On this page

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#

  1. Content Types
  2. Search Endpoints
  3. Autocomplete
  4. Search Analytics
  5. Indexing (Admin)
  6. Error Handling

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:

bash
curl -X GET "https://api.lilith.app/v1/search?q=meditation&types=lesson,meditation&difficulty=beginner&size=10" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{
  "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:

json
{
  "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:

bash
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:

json
{
  "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:

bash
curl -X GET "https://api.lilith.app/v1/search/autocomplete?prefix=med&types=meditation&size=5" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{
  "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:

bash
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:

json
{ "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:

bash
curl -X GET "https://api.lilith.app/v1/search/analytics?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{
  "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:

bash
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):

json
{ "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:

bash
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:

json
{
  "success": 2,
  "failed": 0,
  "errors": [],
  "took": 150
}

Remove from Index#

Remove content from the search index.

Endpoint: DELETE /v1/search/index/:contentType/:id

Request:

bash
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:

bash
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:

bash
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#

json
{
  "code": "INVALID_REQUEST",
  "message": "startDate and endDate query parameters are required"
}

SDK Integration#

TypeScript/JavaScript#

typescript
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',
});


Questions?#

  • Technical Support: api-support@lilith.app
  • Documentation: GitHub Issues