Find Entity Occurrences
GET /api/writing/entities/{entity_name}/occurrences
🔍 Find all occurrences of an entity across documents
Searches through all stored documents to find mentions of the specified entity, returning context snippets and positions for each occurrence. Enables cross-document entity navigation and analysis.
Path Parameters:
entity_name: Name of the entity to search for
Query Parameters:
entity_type: Optional filter by entity type (character, location, etc.)max_results: Maximum occurrences to return (1-100, default: 50)
Dependencies:
writing_service: Injected IshvanaWritingModule instance
Returns:
- EntityOccurrencesResponse with occurrences list and counts
Raises:
HTTPException 500: If search fails
Example Response:
{
"entityName": "Aragorn",
"entityType": "character",
"totalOccurrences": 15,
"documentsCount": 3,
"occurrences": [
{
"documentId": "doc-123",
"documentTitle": "Chapter 1",
"contextSnippet": "...when Aragorn arrived at...",
"startPos": 10,
"endPos": 17,
"lineNumber": 42
}
]
}Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Query Parameters
Section titled “Query Parameters ”Responses
Section titled “ Responses ”Successful Response
Response containing all occurrences of an entity across documents.
Fields: entity_name: Name of the entity searched for entity_type: Type of the entity (if known) total_occurrences: Total number of occurrences found documents_count: Number of documents containing the entity occurrences: List of individual occurrences with context
Used By: - GET /api/writing/entities/{name}/occurrences endpoint - Entity panel “Find in Documents” action - Cross-document entity analysis
object
Single occurrence of an entity within a document.
Represents where an entity appears in a document with context snippet and position information for navigation.
Fields: document_id: ID of the document containing the occurrence document_title: Title of the document context_snippet: Text snippet surrounding the entity mention start_pos: Start position of the entity in the snippet end_pos: End position of the entity in the snippet line_number: Optional line number in the document
Used By: - GET /api/writing/entities/{name}/occurrences endpoint - Entity search results UI - Cross-document entity navigation
Validation Error