---
name: moviepilot-api
version: 50
description: >-
  Use this skill for MoviePilot product operations such as media search, torrent
  search, downloads, subscriptions, library checks, sites, storage, workflows,
  schedulers, plugins, filter rules, and system settings. It authorizes the
  structured moviepilot_api gateway only; it does not authorize arbitrary HTTP,
  legacy Agent tools, MCP compatibility commands, authentication headers, or API
  tokens.
allowed-tools: moviepilot_api
allowed-api-operations: >-
  media.search media.person.search media.person.credits media.recognize media.scrape
  media.episode_schedule media.detail subscription.add subscription.update subscription.search
  subscription.list subscription.shares subscription.popular subscription.history
  subscription.delete download.add download.artist_collection download.tasks.active
  download.clients download.paths download.history.list download.history.delete
  transfer.history.delete site.update site.list site.userdata site.test site.cookie.update
  recommendation.list library.exists library.latest storage.settings storage.list transfer.history
  transfer.file scheduler.list scheduler.run workflow.list workflow.run plugin.installed
  plugin.market plugin.capabilities plugin.config.get plugin.config.update plugin.source.options
  plugin.source.install plugin.source.change plugin.reload plugin.install plugin.uninstall
  slash.list config.identifiers.get config.identifiers.update search.torrents search.results
  filter.builtin filter.custom filter.groups filter.custom.add filter.custom.update
  filter.custom.delete filter.group.add filter.group.update filter.group.delete plugin.data
  config.system.list config.system.describe config.system.get config.system.update slash.run
  music.recognize music.explore music.album.get music.album.related music.artist.get
  music.artist.albums music.artist.related music.cache.get music.cache.delete music.cache.clear
  system.versions system.update.status system.update.check system.update.download system.restart
  system.update.install system.upgrade.dev dashboard.media.statistics dashboard.storage
  dashboard.processes dashboard.system dashboard.downloader scheduler.progress
  dashboard.transfer.statistics dashboard.cpu dashboard.memory dashboard.network media.sources
  media.recognize_file media.cache.get media.cache.delete media.cache.clear
  media.classification.fields media.classification.policy.get media.classification.policy.validate
  media.classification.policy.preview media.classification.policy.impact
  media.classification.policy.history media.classification.policy.update
  media.classification.policy.rollback media.episode_groups media.episode_group.seasons
  media.seasons search.title search.recommend subtitle.search.title subtitle.search.media site.add
  site.delete site.auth.options site.authenticate site.cookiecloud.sync site.cookie.set site.reset
  site.priorities.update site.userdata.refresh site.userdata.latest site.category site.resource
  site.searchable site.rss site.statistics site.statistic site.mapping site.supporting
  subscription.get subscription.find subscription.delete_by_media subscription.status.update
  subscription.reset subscription.search_all subscription.refresh subscription.metadata.refresh
  subscription.history.delete subscription.user.list subscription.files
  subscription.execution.list subscription.execution.get subscription.execution.cancel
  subscription.share subscription.share.delete subscription.fork subscription.follow.list
  subscription.follow.add subscription.follow.delete subscription.share.statistics storage.manage
  storage.mkdir storage.rename storage.delete transfer.queue transfer.queue.delete transfer.name
  transfer.target_path transfer.manual_history transfer.episode_format.recommend
  transfer.manual_reviews transfer.manual_review transfer.manual_review.resolve
  transfer.history.redo transfer.history.redo_batch transfer.history.clear workflow.create
  workflow.get workflow.update workflow.delete workflow.actions workflow.event_types
  workflow.plugin.actions workflow.start workflow.pause workflow.reset workflow.shares
  workflow.share workflow.share.delete workflow.fork torrent.cache.get torrent.cache.delete
  torrent.cache.clear torrent.cache.refresh torrent.cache.reidentify database.backups.list
  database.backups.create database.backups.verify database.backups.delete filter.test
  system.network.targets system.network.test system.module.list system.module.catalog
  system.module.settings system.module.test plugin.market.sync_wiki plugin.runtime.status
  plugin.history plugin.releases plugin.ratings plugin.rating plugin.rating.submit
  plugin.statistics plugin.reset plugin.clone.restorable plugin.clone config.user.get
  config.public.get system.usage.statistics plugin.folders.get plugin.folders.update
  plugin.folder.create plugin.folder.update plugin.folder.delete plugin.folder.plugins.update
  plugin.folder.plugin.assign plugin.folder.plugin.remove plugin.loglevel.get plugin.loglevel.set
  plugin.loglevel.clear plugin.default_target.set plugin.default_target.clear
  plugin.instance.set_enabled plugin.instance.purge
---

# 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](api/subscription.md)
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.

```json
{"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](api/config.md) | `config.*` | identifiers, public/user settings, system setting discovery and updates |
| Dashboard | [api/dashboard.md](api/dashboard.md) | `dashboard.*` | media, storage, process, system, downloader, CPU, memory, network, and transfer summaries |
| Database | [api/database.md](api/database.md) | `database.backups.*` | administrator backup lifecycle |
| Download | [api/download.md](api/download.md) | `download.*` | download submission, clients, paths, active tasks, and history |
| Filter | [api/filter.md](api/filter.md) | `filter.*` | built-in/custom rules, groups, and testing |
| Library | [api/library.md](api/library.md) | `library.*` | existence and latest-media checks |
| Media | [api/media.md](api/media.md) | `media.*` | media search/detail, recognition, scraping, schedules, sources, people, seasons, and classification |
| Music | [api/music.md](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](api/plugin.md) | `plugin.*` | plugin market, install/runtime, configuration, source, folders, ratings, releases, and statistics |
| Recommendation | [api/recommendation.md](api/recommendation.md) | `recommendation.*` | recommendation listings |
| Scheduler | [api/scheduler.md](api/scheduler.md) | `scheduler.*` | scheduler listing, progress, and execution |
| Search | [api/search.md](api/search.md) | `search.*` | title, torrent, result, and recommendation search |
| Site | [api/site.md](api/site.md) | `site.*` | site discovery, authentication, cookies, user data, resources, RSS, priorities, and statistics |
| Slash | [api/slash.md](api/slash.md) | `slash.*` | slash-command discovery and execution |
| Storage | [api/storage.md](api/storage.md) | `storage.*` | storage settings, browsing, directories, rename, and delete |
| Subscription | [api/subscription.md](api/subscription.md) | `subscription.*` | subscription CRUD, search/refresh, history, files, sharing, following, and status |
| Subtitle | [api/subtitle.md](api/subtitle.md) | `subtitle.search.*` | subtitle title and media search |
| System | [api/system.md](api/system.md) | `system.*` | versions, update, restart, modules, network, and usage |
| Torrent cache | [api/torrent.md](api/torrent.md) | `torrent.cache.*` | torrent-cache inspection, refresh, re-identification, and deletion |
| Transfer | [api/transfer.md](api/transfer.md) | `transfer.*` | transfer queue/history, file, naming, manual review, retry, and target path |
| Workflow | [api/workflow.md](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

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:

```json
{
  "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` |

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](code-execution.md) 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.