api
endpoints
http
Engine API Reference
Base URL: http://localhost:61495
Interactive documentation: http://localhost:61495/swagger
All endpoints require authentication unless noted. Three roles: Administrator (full access), Curator (browse + metadata), Consumer (browse only). API keys are passed as X-Api-Key header.
System
Method
Path
Description
Auth
GET
/system/statusService health, version, uptime
None
GET
/system/watcher-statusFile watcher diagnostic — shows monitored folders and last event
Required
POST
/maintenance/sweep-orphan-imagesScan .data/images/ for directories with no matching database record and remove them. Skips user-uploaded images (user_override flag).
Administrator
Library
Method
Path
Description
Auth
GET
/library/worksAll works with their canonical values
Required
Hubs
Method
Path
Description
Auth
GET
/hubsAll media hubs (Series) with their child works
Required
GET
/hubs/search?q=Search hubs by name. Returns matching Series and Universes.
Required
Registry
Method
Path
Description
Auth
GET
/registry/itemsPaginated item list. Supports filtering by status, media type, hub, and search term.
Required
GET
/registry/items/{entityId}/detailFull item detail including all claims, canonical values, pipeline state, and linked persons
Required
GET
/registry/countsStatus counts for Vault badge indicators (Verified, Provisional, Needs Review, Quarantined)
Required
GET
/registry/state-counts?batchId=Four-state counts scoped to a specific ingestion batch
Required
Method
Path
Description
Auth
GET
/metadata/claims/{entityId}All claims for an entity, grouped by field, with source and confidence
Required
GET
/metadata/conflictsAll unresolved metadata conflicts across the library
Curator
GET
/metadata/{entityId}/canon-discrepanciesField-level mismatches between the canonical value and file-embedded metadata
Required
Streaming
Method
Path
Description
Auth
GET
/stream/{assetId}Stream media file. Supports HTTP 206 byte-range requests for seeking.
Required
GET
/stream/{assetId}/coverFull-size cover art (JPEG)
Required
GET
/stream/{assetId}/cover-thumb200px-wide thumbnail (JPEG, quality 75, SkiaSharp-generated)
Required
Ingestion
Method
Path
Description
Auth
POST
/ingestion/scanDry-run scan of configured library folders. Reports what would be ingested without making changes.
Administrator
POST
/ingestion/library-scanScan library folders and update known file paths. Triggers ingestion for new files.
Administrator
GET
/ingestion/watch-folderReturns current watch folder configuration
Required
Search
Method
Path
Description
Auth
POST
/search/universeSearch Wikidata for entity candidates by title, author, and media type
Curator
POST
/search/retailSearch configured retail providers for matching candidates
Curator
POST
/search/resolveUnified resolve search — queries all active providers and returns ranked candidates
Curator
Review Queue
Method
Path
Description
Auth
GET
/review/pendingAll items currently in the review queue
Curator
GET
/review/countCount of pending review items. Used for Vault badge.
Required
GET
/review/{id}Full detail for a single review item including candidates
Curator
POST
/review/{id}/resolveResolve a review item by selecting a candidate QID or confirming provisional metadata
Curator
POST
/review/{id}/dismissDismiss a review item without resolving it
Curator
POST
/review/{id}/skip-universeMark the item as confirmed without universe matching (no QID assignment)
Curator
Persons
Method
Path
Description
Auth
GET
/persons/{id}Person detail — biographical data, roles, library presence, social links
Required
GET
/persons/{id}/aliasesPseudonym list for a person, including resolved Wikidata aliases
Required
Universes
Method
Path
Description
Auth
GET
/universesAll narrative roots (Universes) in the library
Required
GET
/universe/{qid}Universe detail — Series, People, and asset counts
Required
GET
/universe/{qid}/healthHealth score — completeness, enrichment freshness, missing metadata indicators
Required
GET
/universe/{qid}/graphGraph data in Cytoscape.js format for the Chronicle Explorer visualization
Required
GET
/universe/{qid}/pathsFind shortest paths between two entities within the universe graph
Required
GET
/universe/{qid}/family-treeCharacter family tree rooted at a specified character entity
Required
GET
/universe/{qid}/cross-mediaEntities that appear across more than one media type within the universe
Required
GET
/universe/{qid}/castCharacters with their linked performers, including era-correct actor data
Required
GET
/universe/{qid}/adaptationsAdaptation chain — all works derived from or adapted into each other
Required
AI
Method
Path
Description
Auth
GET
/ai/statusAI subsystem health — model load state, hardware tier, resource pressure
Required
GET
/ai/modelsStatus of all configured models (loaded, unloaded, downloading, unavailable)
Required
POST
/ai/models/{role}/downloadTrigger download for a model role (text_fast, text_quality, text_scholar, text_cjk, audio)
Administrator
POST
/ai/models/{role}/loadLoad a model into memory
Administrator
POST
/ai/models/{role}/unloadUnload a model from memory
Administrator
GET
/ai/configFull AI configuration
Administrator
PUT
/ai/configUpdate AI configuration
Administrator
GET
/ai/profileHardware profile — benchmark results, tier classification, GPU backend
Required
POST
/ai/benchmarkRe-run hardware benchmark and reclassify tier
Administrator
GET
/ai/resourcesLive system resource usage — CPU load, RAM pressure, active transcoding tasks
Required
GET
/ai/enrichment/progressBackground enrichment batch progress
Required
GET
/ai/enrich/tldr/{entityId}Generate a TL;DR summary for a work using its description
Curator
GET
/ai/enrich/vibes/{entityId}Generate vibe tags for a work
Curator
POST
/ai/enrich/search/intentParse a natural-language search query into structured field filters
Required
POST
/ai/enrich/extract-urlExtract metadata from a URL (book page, IMDB entry, etc.)
Curator
Enrichment
Method
Path
Description
Auth
POST
/metadata/pass2/triggerManually trigger a Pass 2 (deep enrichment) run for one or more entity IDs
Curator
GET
/metadata/pass2/statusCurrent Pass 2 run status — progress, queue depth, last completed
Required
Activity
Method
Path
Description
Auth
GET
/activity/recentRecent system activity entries, newest first
Required
POST
/activity/prunePrune activity entries older than the configured retention period
Administrator
GET
/activity/statsAggregated activity statistics — counts by type and outcome
Required
PUT
/activity/retentionUpdate the activity retention period (days)
Administrator
GET
/activity/by-typesFilter activity log by one or more activity type codes
Required
GET
/activity/run/{runId}All activity entries for a specific ingestion or enrichment run
Required
Admin
Method
Path
Description
Auth
GET
/admin/api-keysList all API keys with labels, roles, and creation dates (keys are not returned after creation)
Administrator
POST
/admin/api-keysGenerate a new API key with a label and role
Administrator
DELETE
/admin/api-keys/{keyId}Revoke an API key immediately
Administrator
GET
/admin/provider-configsList all provider configurations
Administrator
PUT
/admin/provider-configs/{providerId}Update a provider configuration
Administrator
DELETE
/admin/provider-configs/{providerId}Remove a provider configuration
Administrator
Settings
Method
Path
Description
Auth
GET
/settings/foldersList configured library folder paths
Required
PUT
/settings/foldersUpdate library folder configuration
Administrator
POST
/settings/test-pathTest whether a filesystem path is accessible by the Engine
Administrator
GET
/settings/providersProvider configuration status — enabled state, last health check, rate limit info
Required
GET
/settings/server-generalCore server settings (name, language preferences, country)
Required
PUT
/settings/server-generalUpdate core server settings
Administrator
Profiles
Method
Path
Description
Auth
GET
/profilesList all user profiles
Required
POST
/profilesCreate a new profile
Administrator
GET
/profiles/{id}Profile detail
Required
PUT
/profiles/{id}Update a profile
Administrator
DELETE
/profiles/{id}Delete a profile
Administrator
UI Settings
Method
Path
Description
Auth
GET
/settings/ui/globalGlobal UI defaults
Required
PUT
/settings/ui/globalUpdate global UI defaults
Administrator
GET
/settings/ui/device/{class}Device profile settings for a device class (web, mobile, television, automotive)
Required
PUT
/settings/ui/device/{class}Update device profile settings
Administrator
GET
/settings/ui/profile/{id}Per-user UI preference overrides for a profile
Required
PUT
/settings/ui/profile/{id}Update per-user UI preferences
Required
GET
/settings/ui/resolvedEffective resolved settings for the current request context (global + device + profile merged)
Required
Reader
Method
Path
Description
Auth
GET
/read/{assetId}/metadataEPUB metadata — title, author, language, cover
Required
GET
/read/{assetId}/tocTable of contents
Required
GET
/read/{assetId}/chapter/{index}Chapter content by index
Required
GET
/read/{assetId}/resource/{path}Embedded resource (CSS, image) by path within the EPUB
Required
GET
/read/{assetId}/searchFull-text search within EPUB content
Required
GET
/reader/{assetId}/bookmarksList bookmarks for an asset
Required
POST
/reader/{assetId}/bookmarksCreate a bookmark
Required
DELETE
/reader/{assetId}/bookmarks/{bookmarkId}Delete a bookmark
Required
GET
/reader/{assetId}/highlightsList highlights
Required
POST
/reader/{assetId}/highlightsCreate a highlight
Required
DELETE
/reader/{assetId}/highlights/{highlightId}Delete a highlight
Required
GET
/reader/{assetId}/statisticsReading statistics — time spent, completion percentage, sessions
Required
POST
/read/{assetId}/whispersyncSync reading position across devices
Required
GET
/read/{assetId}/whispersyncRetrieve last sync position
Required
DELETE
/read/{assetId}/whispersyncClear sync position
Required
Progress
Method
Path
Description
Auth
GET
/progress/{assetId}Playback or reading progress for an asset
Required
PUT
/progress/{assetId}Update progress
Required
GET
/progress/recentRecently accessed assets with progress
Required
GET
/progress/journeyFull reading/watching journey across all assets for the current profile
Required
Reports
Method
Path
Description
Auth
POST
/reportsSubmit a metadata quality report for an entity
Required
GET
/reports/entity/{id}All reports for a specific entity
Curator
POST
/reports/{id}/resolveMark a report as resolved
Curator
POST
/reports/{id}/dismissDismiss a report
Curator
Vault
Method
Path
Description
Auth
GET
/vault/characters/{id}/portraitsPortrait images for a fictional character
Required
GET
/vault/persons/{id}/character-rolesCharacters a person has performed, linked to works
Required
GET
/vault/universes/{qid}/charactersAll characters in a universe
Required
GET
/vault/assets/{entityId}Shared assets for an entity (Cover Art, Headshot, Banner, Logo, Backdrop)
Required
POST
/vault/enrichment/universe/triggerTrigger universe enrichment for a specific QID
Curator
SignalR
Hub
Path
Direction
Description
Intercom
/hubs/intercomServer → Client
Real-time push events: ingestion progress, enrichment completion, pipeline state changes, review queue updates. Authentication required. Server-push only — clients do not send messages to the hub.
Development
Available in development environments only. These endpoints are removed in production builds.
Method
Path
Description
POST
/dev/seed-librarySeed the library with 22 EPUB test cases covering edge cases (pen names, foreign languages, series grouping, multi-author)
POST
/dev/wipeWipe the database and staging area. Irreversible.
POST
/dev/full-testRun full ingestion and enrichment pipeline on the seeded test library
POST
/dev/integration-testRun the integration test suite and return an HTML report