# Content Search API

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](#content-types)
2. [Search Endpoints](#search-endpoints)
3. [Autocomplete](#autocomplete)
4. [Search Analytics](#search-analytics)
5. [Indexing (Admin)](#indexing-admin)
6. [Error Handling](#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',
});
```

---

## Related Documentation

- [Lesson API](./lesson-api.md) - Course lesson management
- [Meditation API](./meditation-api.md) - Meditation content management
- [Recommendation API](./recommendation-api.md) - Content recommendations
- [Authentication](./authentication.md) - API authentication

---

## Questions?

- **Technical Support**: api-support@lilith.app
- **Documentation**: [GitHub Issues](https://github.com/lilith/platform/issues)
