Advanced Search Documents
POST /api/writing/search/advanced
🔍 Perform advanced search on writing documents
Executes sophisticated semantic search with multiple filters, facets, and sorting options for comprehensive document discovery. Supports full-text search, metadata filtering, and relevance ranking.
Request Body:
request: AdvancedSearchRequest with query, filters, facets, and sort options
Dependencies:
writing_service: Injected IshvanaWritingModule instance
Returns:
- AdvancedSearchResponse with ranked results, facets, and search metadata
Raises:
HTTPException 500: If search operation fails
Example Response:
{
"results": [...],
"facets": {"types": {...}, "tags": {...}},
"total_count": 42,
"search_time_ms": 125
}Request Body required
Section titled “Request Body required ”Advanced document search request model with facets and filters.
Request model for advanced semantic search with faceted navigation, custom filters, and pagination support.
Fields: query: Semantic search query string filters: Optional filters dictionary (e.g., {“type”: “lore”, “tags”: “worldbuilding”}) facets: Optional list of facets to return (e.g., [“document_type”, “tags”]) limit: Maximum results per page (default: 20) offset: Result offset for pagination (default: 0) project_id: Optional project ID to scope search within a project include_snippets: Whether to include content snippets in results (default: False) type: Optional document type filter (e.g., “document”, “note”, “lore”) requested_at: Search request timestamp (auto-generated)
Used By: - POST /api/writing/search/advanced endpoint - Advanced search UI with faceted navigation - Complex search queries with filtering - Search result refinement
object
Advanced search request timestamp
Responses
Section titled “ Responses ”Successful Response
Advanced search response model with facets and performance metrics.
Provides search results with faceted navigation options, total count, and search performance metrics.
Fields: documents: Ordered list of matching documents (by relevance) facets: Available facets with values and counts total_count: Total number of matching documents search_time_ms: Search execution time in milliseconds
Facets Example: { “document_type”: [{“value”: “lore”, “count”: “42”}], “tags”: [{“value”: “worldbuilding”, “count”: “38”}] }
Used By: - POST /api/writing/search/advanced endpoint response - Advanced search UI with facets - Search performance monitoring - Result filtering and navigation
object
Document metadata model for writing documents.
Comprehensive metadata model for all writing documents including creative writing, lore entries, worldbuilding documents, and general notes. Uses IshvanaBaseModel for automatic snake_case → camelCase JSON conversion.
Fields:
document_id: Unique document identifier
project_id: Owning project ID (empty string for unscoped documents)
title: Document title
document_type: Type classification (lore, character, location, general)
tags: Categorization and search tags
created_at: Creation timestamp (auto-generated)
updated_at: Last modification timestamp (auto-generated)
version: Current version number (increments on each update)
word_count: Total word count for writing metrics
custom_fields: User-defined custom metadata
folder_id: Containing folder ID, None for top-level
is_fork_branch: Whether this document is a fork branch off a root
Used By: - DocumentListResponse for document listings - DocumentResponse for single document retrieval - AdvancedSearchResponse for search results - Document browser and editor UI - Version history tracking
object
Document creation timestamp
Last update timestamp
object
object
object
Validation Error