Repository navigation
Home
Welcome to the Orca-Engine wiki!
Version: 1.2.4.0-beta
Target: Jellyfin 10.11.x plugin
API base: /OrcaEngine
Status: Beta
This document describes the HTTP API currently exposed by Orca Engine.
The route inventory is based on the current source-code inventory. Where the available information does not include an exact request body, query parameter, response schema, or authentication requirement, it is marked as needs confirmation rather than guessed.
Orca Engine is exposed through the Jellyfin server hosting the plugin.
A typical request is:
http(s)://<jellyfin-host>:<port>/OrcaEngine/<route>Examples:
GET /OrcaEngine/Health
GET /OrcaEngine/Home
GET /OrcaEngine/Recommendations
GET /OrcaEngine/BootstrapThe source inventory identifies three route classes:
anon— no authentication attributeauth— authenticated requestadmin— requires Jellyfin elevation
Many client-facing routes currently allow anonymous access. This is part of the current beta implementation and should be considered when exposing the server outside a trusted network.
Returns server capabilities together with the fully composed home screen in one request. This is the preferred startup contract for clients such as OrcaX.
Status: Implemented
External configuration: None for basic operation
Exact response model: Needs confirmation from the current controller/model definitions.
Returns the server-composed home screen. Current row providers include Continue Watching, For You, Because You Watched, Trending, You Might Like, New Since, Coming Soon, Continue the Story, Mood Collections, Discover and Recently Added.
Status: Implemented
Response model: Needs confirmation.
Returns plugin/server liveness information and the Orca Engine version.
Status: Implemented.
Returns ranked recommendations. The server performs candidate generation, eligibility filtering, scoring and diversity selection.
Status: Implemented.
Re-ranks a supplied candidate set using Orca Engine's ranking logic.
Status: Implemented.
Input fields: Needs confirmation from the controller signature.
Returns similar content using the content-vector index.
Status: Implemented, but requires an embedding provider for usable similarity results.
Input fields: Needs confirmation.
Returns genre relationship/adjacency information.
Status: Implemented.
Returns related genres for the supplied input.
Status: Implemented.
Input fields: Needs confirmation.
Records explicit user feedback such as thumbs up/down.
Status: Implemented.
Request DTO: Needs confirmation.
Accepts batched client behaviour/card telemetry events.
Status: Implemented.
Request DTO: Needs confirmation.
For clients, batching events is preferable to sending a request for every UI interaction.
Returns recent behaviour events for inspection.
Status: Implemented.
Returns behaviour/event statistics.
Status: Implemented.
Returns the current personalization profile.
Status: Implemented.
Returns the user's stored taste profile. The current model tracks affinity across genre, studio, tag, decade, media type, person, runtime, maturity, language and franchise, with daypart variants and confidence/decay handling.
Status: Implemented.
Recomputes personalization information.
Status: Implemented.
Parameters: Needs confirmation.
Rebuilds the stored taste profile.
Status: Implemented.
Parameters: Needs confirmation.
Returns server configuration exposed through the API.
Returns feature/capability flags used by clients to determine which optional features are available.
Both are implemented.
Returns roaming per-user settings.
Creates or updates roaming per-user settings.
Deletes stored roaming per-user settings.
These are implemented. Request/response schema needs confirmation.
Submits a media request.
Status: Implemented, but requires the Feature Requests capability and Jellyseerr integration.
Returns request status.
Status: Implemented, but requires the relevant integration/configuration.
Parameters: Needs confirmation.
Resolves/serves a trailer for a TMDB item.
Returns trailer processing/cache state.
Starts trailer prebuffering.
Requests trailer prefetching/warming.
These routes are implemented, but trailer functionality requires the configured trailer tooling, including yt-dlp and ffmpeg.
Returns trivia for a title.
Status: Implemented, but requires an LLM configuration.
Returns content advisories/warnings.
Status: Implemented, but requires an LLM configuration.
Returns a watch-provider logo/image.
Status: Implemented.
Returns a card preview payload.
Status: Implemented.
Known limitation: the current preview path contains a hardcoded Progress = 0.4 demo value and should not be treated as live playback progress.
Returns the latest OrcaX release information exposed by the server.
Serves a specific OrcaX APK release asset.
Both are implemented.
Returns the current per-user discovery picks.
Status: Implemented, requires TMDB configuration.
Triggers or requests discovery-pick retrieval.
Status: Implemented, requires TMDB configuration.
Returns funnel analytics.
Returns popularity analytics.
Returns community-rating analytics.
All three are implemented.
Returns catalog statistics/counts.
Status: Implemented.
Searches for available media sources.
Status: Implemented, optional/off by default.
Current dependency: Prowlarr configuration for the source-search path.
The stream controller exposes session operations under:
/OrcaEngine/Stream/Sessions…The current inventory confirms GET/POST/DELETE operations for stream sessions.
Serves byte-range data for an established stream token.
Status: Implemented, optional/off by default.
Exact session route/action names and DTO schemas: Needs confirmation from the controller source before this section is treated as a wire-level reference.
These routes are intended for server administration rather than normal client use.
/OrcaEngine/Admin/Status
/OrcaEngine/Admin/Metrics
/OrcaEngine/Admin/Metrics/Reset
/OrcaEngine/Admin/Diagnostics
/OrcaEngine/Admin/RequestsImplemented and admin/elevated.
/OrcaEngine/Observatory/App
/OrcaEngine/Observatory/Snapshot
/OrcaEngine/Observatory/Events
/OrcaEngine/Observatory/StreamImplemented. The Observatory UI is available at /orca and includes a live SSE event stream.
GET /OrcaEngine/TasteGraph
Admin diagnostics for the taste graph.
/OrcaEngine/Embedding/Diagnostics
/OrcaEngine/Embedding/TestAdmin diagnostics/testing for the configured embedding provider.
/OrcaEngine/Metadata/Diagnostics
/OrcaEngine/Metadata/EnrichWarningsAdmin diagnostics and warning-enrichment operations.
GET /OrcaEngine/Trailer/Diagnostics
Admin diagnostics for the trailer subsystem.
/OrcaEngine/Catalog/Resync
/OrcaEngine/Catalog/Reconcile
/OrcaEngine/Catalog/EnrichTmdb
/OrcaEngine/Catalog/EnrichProviders
/OrcaEngine/Catalog/PurgeUnjustifiedAdmin catalog maintenance operations.
/OrcaEngine/Discovery/Sweep
/OrcaEngine/Discovery/PullGlobal
/OrcaEngine/Discovery/Runs
/OrcaEngine/Discovery/SourceStatsAdmin discovery operations and diagnostics.
GET and POST /OrcaEngine/Behavior/ImportHistory
Reads or triggers the Jellyfin watch-history import. The importer is idempotent.
/OrcaEngine/Stream/Dashboard
/OrcaEngine/Stream/ReachabilityAdmin diagnostics for the optional stream subsystem.
POST /OrcaEngine/Analytics/CommunityRating/Recompute
Recomputes community-rating analytics.
For an OrcaX-style client:
1. GET /OrcaEngine/Health
2. GET /OrcaEngine/Bootstrap
3. Read capabilities/feature flags
4. Render the returned rows and cards
5. Send behaviour events in batches
6. Call feature-specific endpoints when neededThe client should not reproduce Orca Engine's recommendation logic. Orca Engine is responsible for gathering data, personalization, ranking and home composition; the client is responsible for presentation, navigation and playback.
API area | Main dependency -- | -- Bootstrap / Home | None for basic operation Recommendations | Catalog + personalization data Similar | Embedding provider Behaviour | None Personalization | Behaviour/history data Requests | Jellyseerr + feature enabled Discovery | TMDB Metadata trivia/warnings | LLM configuration Trailers | yt-dlp + ffmpeg Sources | Prowlarr Stream sessions | Optional stream subsystem Update | Server-side APK cachePublic API and database schema are still moving during beta.
OnnxEmbeddingProvideris currently a stub and does not provide usable embeddings.There is no automatic embedding-provider fallback.
The vector index is built lazily.
The card preview endpoint contains a hardcoded demo progress value.
Some Jellyfin compatibility handling is version-sensitive.
Many client routes allow anonymous access.
Optional LLM functionality is disabled by default and fails softly.
Optional source/stream functionality is disabled by default.
Orca Engine is currently single-server, in-process and SQLite-based.
For a completely wire-accurate reference, the remaining details to extract directly from the controllers and DTOs are:
Exact request DTOs for POST endpoints.
Exact query/path parameters for GET endpoints.
Exact JSON response models.
Explicit success/error status codes.
Authentication attributes on each individual route.
Exact action names under
/Stream/Sessions….Pagination, filtering and sorting parameters where supported.
Those fields should be documented from the actual method signatures rather than inferred.