MoviePilot API

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.

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.

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.
5. Obtain confirmation for confirmation-protected or side-effecting operations, then execute the gateway call once.
6. Inspect success, execution_outcome, errors, empty results, and collection metadata before reporting or taking a dependent action.
7. Verify writes with the category's read-back operation when the contract requires it; do not repeat a write whose outcome is unknown.

API Category Index

Each category file contains the complete operation contracts for its namespace. The counts are a maintenance aid for the 220 currently exposed operations.

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

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

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:

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.

• 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

• 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.

Operation Order And Failure Handling

1. Select the operation first, then place each value in its documented bucket. Never move query fields into path_params or send undeclared fields.
2. Reuse the exact media_source + media_id pair returned by search. For music, also preserve music_type.
3. Downloads, transfers, configuration/rule/plugin writes, scheduler/workflow runs, and deletions have side effects; obtain confirmation and inspect the result.
4. success=false, HTTP errors, validation errors, and empty results are real outcomes. Never report them as success.
5. Use database-operation, downloader-operation, or mediaserver-operation for their native capabilities. Never bypass the gateway with an arbitrary URL.