moviepilot-api

MoviePilot API

Unhandled exceptions outside the durable transfer step ledger stop automatic replay and create an unhandled_execution_review diagnostic. Repair or disable the failing plugin and inspect the files before resolving it as not_applied; roll back untracked effects first when needed. This diagnostic rejects applied and does not replace the evidence for any recorded file operations.

For relevant prior conversations or previous tool evidence, use the host-provided session_search tool when available. Discover a session, then read its anchored messages; past results are context, not proof of current state or permission to repeat a write. Stable preferences use search_memory; its former activity category no longer exists. Neither tool is an API operation or an external MCP tool.

Use moviepilot_api for normal MoviePilot business operations. The tool accepts only operation_id, path_params, query, and body. The host chooses the fixed HTTP method and path, creates the current user's authentication token, applies authorization and confirmation policy, and returns the API response.

The gateway connects directly to the local backend listener using HOST and PORT, bypassing environment proxies. APP_DOMAIN is for public URLs such as Passkey origins and is not the gateway base URL. Keep it configured even when the public reverse proxy is unreachable from inside the container.

subscription.add, subscription.update, and subscription.delete require authorization for the action and scope and use the active MoviePilot user bound to the channel account, including for channel administrators. Creation belongs to that user; ordinary users may update or delete only their own subscriptions. An unbound or inactive channel user must bind an active account before retrying, not switch to an administrator identity.

For QQ, either qq_userid or qq_openid may match the current channel ID; for Feishu, either feishu_userid or feishu_openid may match. A single matching field is sufficient, but the match must identify exactly one active MoviePilot user across all candidate fields. Do not copy an openid into the userid field as a workaround or bypass an ambiguous binding.

For subscription.update, omit settings that should stay unchanged. Send JSON null to clear a supported optional setting; see Subscription APIs for the exact fields and the form empty-string compatibility rule.

This file is intentionally kept as the routing and execution guide. Detailed operation contracts live in the linked category files under api/; load only the one category file needed for the selected operation. Do not load every category file by default.

Never provide a URL, method, authentication header, API key, or access token. Never fall back to a retired tool name or moviepilot tool MCP command. If an operation is not listed in this skill, do not simulate it through arbitrary HTTP; use a more specific skill or explain that the structured operation is unavailable.

For SMB organization, keep the source FileItem.storage and share-relative path together. Downloader task paths mapped to SMB retain the smb: prefix; never interpret them as local filesystem paths. Same-storage SMB copy, move, and hard-link operations execute on the server and fail without downloading and re-uploading the media when the server cannot perform them. This does not change separate content-processing operations such as embedded music tags. With shares: ["video", "downloads"], paths start with the share name, such as /downloads/Movie.mkv and /video/Movie.mkv. Legacy share keeps share-relative paths. Cross-share moves copy on the server before deleting the source and are not atomic; cross-share hard links are unsupported. Update saved directory and downloader mappings when switching path modes.

Overall Workflow

1. Select the exact operation_id from the category index below.
2. Call read_skill again with name="moviepilot-api" and file="api/<category>.md" to load the complete standalone category contract. Do not use read_file for Skill documents.
3. The selected category file already includes the shared body Models needed to construct its calls; do not load a second Models document.
4. Build one gateway call with only declared fields. Preserve source-native identifiers and use the documented pagination fields. Pass object and array bodies as native JSON values, and pass null only when the selected operation allows it. The only string body is the literal "dev" for system.upgrade.dev. Never flatten operation fields next to operation_id: put each in its declared path_params, query, or body container. Do not copy pagination or filters from another operation. An invalid_input response names the failing field and includes input_contract; correct that field and all required fields before retrying. Invalid input is rejected before the API request is sent.
5. For a side effect, check authorization for the action, target, and scope. Reuse the user's explicit request or earlier authorization without asking again; ask only for missing material choices or expanded scope. Honor any confirmation required by the host, then execute the gateway call once.
6. Inspect success, execution_outcome, errors, empty results, and collection metadata before reporting or taking a dependent action. Never report a failure as success.
7. Verify writes with the category's read-back operation when the contract requires it; do not repeat a write whose outcome is unknown.

Call Shape Examples

Replace example IDs with the exact identifiers returned by earlier calls. These are separate operation contracts, not interchangeable parameter templates.

{"operation_id":"media.detail","path_params":{"media_id":"27205"},"query":{"media_source":"tmdb","type_name":"\u7535\u5f71"}}
{"operation_id":"subscription.execution.list","query":{"limit":10}}
{"operation_id":"site.rss","query":{"page":1,"count":20}}

media.detail requires both the source-native ID and its source/type. Recent subscription executions use limit, not page or count. site.rss lists RSS-enabled sites; it does not accept a site_id filter.

media.detail and transfer.file accept movie, tv, or music in type_name; subscription.add accepts the same values in type. The corresponding Chinese labels remain supported.

API Category Index

Each category file contains the complete operation contracts for its namespace. Use the category contracts and frontmatter allowlist as the operation source of truth.

Category	Detail file	Operation namespace	Use for
Configuration	api/config.md	config.*	identifiers, public/user settings, system setting discovery and updates
Dashboard	api/dashboard.md	dashboard.*	media, storage, process, system, downloader, CPU, memory, network, and transfer summaries
Database	api/database.md	database.backups.*	administrator backup lifecycle
Download	api/download.md	download.*	download submission, clients, paths, active tasks, and history
Filter	api/filter.md	filter.*	built-in/custom rules, groups, and testing
Library	api/library.md	library.*	existence and latest-media checks
Media	api/media.md	media.*	media search/detail, recognition, scraping, schedules, sources, people, seasons, and classification
Music	api/music.md	music.*	recognition, global and per-task CUE policy, exploration, albums, artists, text normalization, edition precedence, and cache administration
Plugin	api/plugin.md	plugin.*	plugin market, install/runtime, configuration, source, folders, ratings, releases, and statistics
Recommendation	api/recommendation.md	recommendation.*	recommendation listings
Scheduler	api/scheduler.md	scheduler.*	scheduler listing, progress, and execution
Search	api/search.md	search.*	title, torrent, result, and recommendation search
Site	api/site.md	site.*	site discovery, authentication, cookies, user data, resources, RSS, priorities, and statistics
Slash	api/slash.md	slash.*	slash-command discovery and execution
Storage	api/storage.md	storage.*	storage settings, browsing, directories, rename, and delete
Subscription	api/subscription.md	subscription.*	subscription CRUD, search/refresh, history, files, sharing, following, and status
Subtitle	api/subtitle.md	subtitle.search.*	subtitle title and media search
System	api/system.md	system.*	versions, update, restart, modules, network, and usage
Torrent cache	api/torrent.md	torrent.cache.*	torrent-cache inspection, refresh, re-identification, and deletion
Transfer	api/transfer.md	transfer.*	transfer queue/history, file, naming, manual review, retry, and target path
Workflow	api/workflow.md	workflow.*	workflow definitions, actions, execution, sharing, and lifecycle

Each category file is a standalone contract: it contains the operation details and the shared request/response body Models needed by that category. If an operation is added or moved, update its category file, this index, the frontmatter allowlist, and the matching gateway contract together.

API Surface Scope

Operations declare an identity scope: public reads external public metadata without requiring a channel account binding; bound_user uses the active MoviePilot user bound to the stable channel sender ID (Web uses its authenticated user ID); admin requires administrator authority. Read-only does not mean public. Channel nicknames never establish identity. Personal records and subscription writes retain their existing ownership and permission checks.

When identity resolution fails, relay the gateway's actual remediation message and sender ID. Channel users bind their own MoviePilot account via avatar > Personal Information > Account Binding, fill the named channel field, and save. Do not invent a Settings > Users binding page, substitute nicknames/group/bot IDs, diagnose an ambiguous binding failure as a network issue, or ask Web users to bind a notification channel. Public operations do not require binding.

This Skill is the complete callable MoviePilot business API surface for the Agent. Every operation in allowed-api-operations has one exact parameter contract in a category file and one matching MCP tools/list branch. There is no hidden fallback to an arbitrary REST route.

MoviePilot's underlying OpenAPI document is larger because it also serves the web UI, authentication, account lifecycle, binary and streaming responses, callbacks, compatibility endpoints, and source-specific presentation routes. Those routes are deliberately not copied into this Skill. A non-listed route must be one of the following before the Agent may use its capability:

• represented by one stable aggregate operation in this Skill;
• owned by downloader-operation, mediaserver-operation, or another domain Skill with its own exact action contract;
• reserved for host transport, identity, UI, streaming, binary, or diagnostic behavior and therefore unavailable as an Agent business action; or
• explicitly unapproved until a role, effect, confirmation, recovery, result, and English parameter contract is added.

The maintained route-by-route inventory is docs/refactor/agent-api-surface-audit.md. Its generated drift test fails when OpenAPI changes without an explicit ownership decision.

The management recovery route POST /api/v1/history/transfer/{history_id}/discard-corrupt is reserved for direct authenticated management clients and is not a callable Agent operation. It clears corrupt task state while retaining the history record.

Calling Contract

Setting a subscription to state S stops queued and running automatic searches at safe boundaries, including new-subscription and site-retry tasks. An explicit subscription search can still search and download once while paused; cancel its execution batch to stop that run. Pausing or cancelling does not remove tasks already submitted to the downloader.

Call the gateway with this shape:

{
  "operation_id": "media.search",
  "path_params": {},
  "query": {"title": "The Wandering Earth", "type": "media"},
  "body": {}
}

Common read and download contracts

Select the operation for the task first, then send only fields declared by that operation. Common verification contracts are:

operation_id	path_params	query
subscription.find	media_id	media_source; optional season, music_type
subscription.list	none	optional page, count
download.tasks.active	none	optional page, count, name
site.list	none	optional page, count, name, status=all|active|inactive

Subscription execution logs are browser resource endpoints: GET /api/v1/subscribe/{subscription_id}/logs (SSE, or text with length=-1) and /logs/download (ZIP). They require the existing resource Cookie and enforce subscription ownership; they are not JSON gateway or MCP tools. Do not pass a logfile path or try to call them through call_api. Read subscription status through the supported subscription operations; completion of a search task does not prove completion of the subscription.

The download.add body must contain torrent_in (at least title and enclosure) plus sibling media_source and media_id; do not put a magnet URI in url, or move media identity and filters into query. When a write returns unknown, never retry it; verify the actual state with a supported read operation first.

Preserve the candidate's site ID and download URL. For direct HTTP(S) torrents, site_cookie may be omitted: the backend fills a missing Cookie and User-Agent from the configured site only when the download URL matches its scheme, host, and port. Without a site ID, this requires exactly one matching configured site. Explicit credentials and proxy selection are preserved. Magnet and two-step token exchange downloads retain their existing credential rules.

• Put route placeholders such as subscribe_id, hashString, plugin_id, workflow_id, media_id, storage, rule_id, and name in path_params.
• Put GET filters and control values in query. The gateway also accepts GET values in body, but use query consistently except for the protected secret flow below.
• Put POST, PUT, and PATCH request models in body.
• Preserve the exact source-native media_source + media_id returned by a search or detail response. For music, also preserve music_type=recording|album|artist; an artist is browse-only.
• Treat success=false, HTTP error data, empty results, and validation errors as real outcomes. Do not claim success without checking the response.
• Respect an explicit execution_outcome: pending is accepted but unfinished, while unknown means a write may have happened. Do not repeat an unknown write or change defaults merely to evade duplicate protection. In the built-in Agent, use get_tool_execution with the returned invocation ID; the host can reconcile supported non-sensitive setting replacements through a read-only check.
• When a built-in Agent preview contains result_id and next_offset, use read_tool_result for the next page instead of repeating the operation. These receipt and result tools are internal to the Agent, not external MCP tools.

Collection Counts And Pagination

• Search SSE manual_paging=true is a Web-only page-by-page mode and adds no Agent operations; keep using the documented search.* operations. Web streams search sites concurrently and emit append previews before the final filtered page; only the completed result carries source state for advancing page numbers.
• For list inspection, explicitly send the operation's documented pagination fields instead of requesting an unbounded legacy result. For optional legacy pagination, start with query={"page":1,"count":20}.
• For a count or summary request when the operation documents an exact total, send query={"page":1,"count":1} and read collection.total_count. This is the authoritative count after the endpoint's authorization scope and filters.
• A large item list or tool_result_truncated=true does not make the total unavailable. The gateway places collection before data, so its exact metadata remains visible in the bounded preview. Never query the MoviePilot database merely to recover a total already declared by the API contract.
• Use database-operation only for administrator diagnostics or aggregations that the business API cannot express. Do not use it as a fallback for an API list count. If an operation explicitly omits collection.total_count, do not infer a total from one page; continue its native pagination or state that the upstream total is unavailable.

Cross-Skill Routing

Use downloader-operation for downloader instances, task inspection, and native task control. Use mediaserver-operation for libraries, items, playback sessions, scans, refreshes, and other native media-server capabilities. Never bypass the gateway with an arbitrary URL.

For three or more read-only calls with paging or aggregation, load Python aggregation and use execute_code when available.

Reusable learning

When available, use skills_list and skill_view to read personal skills, and skill_manage only within the authorized authoring/review scope; they never grant API operation scopes. Load the public domain skill with read_skill as usual. Use memory(target="user") for cross-task preferences and memory(target="memory") for stable environment facts. Procedures belong in the relevant skill, not duplicated in both stores. A background proposal to replace/remove memory needs the user's explicit /memory approve ID; never infer that confirmation from a tool result or a prior conversation.