List Writing Documents
GET /api/writing/documents
📑 Get a paginated list of writing documents
Retrieves documents with pagination support and optional type filtering. Returns comprehensive metadata including document count, creation dates, and tags for efficient document management.
Query Parameters:
limit: Maximum documents to return (1-100, default: 20)offset: Number of documents to skip for pagination (default: 0)document_type: Filter by document type (optional)
Dependencies:
writing_service: Injected IshvanaWritingModule instance
Returns:
- DocumentListResponse with documents list and pagination metadata
Raises:
HTTPException 500: If document retrieval fails
Example Response:
{
"documents": [...],
"total_count": 150,
"limit": 20,
"offset": 0
}Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Responses
Section titled “ Responses ”Successful Response
Comprehensive Writing integration payload - MERGED response model.
Combines frontend IPC contract requirements with backend pagination fields to maintain backward compatibility while providing orchestrator integration.
Frontend IPC Contract Fields: documents: List of user documents (required by orchestrator) templates: Writing templates (required by orchestrator) versions: Document version history (required by orchestrator) recentSearches: Recent semantic searches (required by orchestrator)
Backend Pagination Fields (preserved for compatibility): total_count: Total documents count (used by old clients) limit: Page size limit (used by old clients) offset: Pagination offset (used by old clients)
object
User documents
Writing document item for frontend IPC contract.
Minimal document model matching frontend DocumentItemSchema contract. Used for orchestrator integration and frontend display.
Fields: id: Document ID title: Document title content: Document content word_count: Word count created_at: Creation timestamp (Unix timestamp in milliseconds) updated_at: Last update timestamp (Unix timestamp in milliseconds)
object
Writing templates
Document template model with variable substitution.
Represents a reusable document template with placeholders for variable substitution, enabling rapid document creation with consistent structure.
Fields: template_id: Unique template identifier name: Template name description: Template purpose and usage description category: Template category for organization content: Template content with variable placeholders variables: List of variable names for substitution
Variable Format: Content: “The {{character_name}} wielded the {{weapon_name}}” Variables: [“character_name”, “weapon_name”]
Used By: - TemplateResponse for template retrieval - DocumentFromTemplateRequest for instantiation - Template browser and selection UI - Rapid document creation workflows
object
Document versions
Individual document version model.
Represents a single version in a document’s version history with metadata for version tracking, comparison, and rollback operations.
Fields: version_number: Version identifier (incremental integer) created_at: Timestamp when this version was created word_count: Word count at this version content_hash: SHA256 hash for content integrity verification version_id: Optional unique version identifier created_by: Optional author/creator of this version content_preview: Optional preview snippet of version content change_description: Optional description of changes in this version
Used By: - VersionHistory for version listing - Version comparison operations - Version rollback functionality - Document history timeline
object
Version creation timestamp
Word count at this version
Recent semantic searches
Semantic search result model.
Represents a single document result from semantic search operations including document identification, similarity scoring, and metadata for enhanced semantic search and similarity analysis.
Fields:
document_id: Unique identifier of the matched documentsimilarity_score: Semantic similarity score (0.0-1.0) indicating how closely the document matches the search querymetadata: Dictionary containing document metadata including:- Document title, type, and creation date
- Project association and tags
- Content preview and word count
Usage: Used within semantic search endpoints:
- POST /api/discovery/enhanced-search/semantic-search returns list of this model
- POST /api/discovery/enhanced-search/similar-documents returns list of this model
JSON Example:
{
"documentId": "doc_123",
"similarityScore": 0.87,
"metadata": {
"title": "API Documentation",
"type": "documentation",
"project": "ishvana"
}
}Total documents count
Page size limit
Pagination offset
Validation Error