Use this skill when you need to call MoviePilot REST API endpoints directly with the bundled Python client. Covers MoviePilot HTTP endpoints across media search, downloads, subscriptions, library management, site management, system administration, plugins, workflows, and more. Prefer `moviepilot-cli` for normal local MCP tool workflows; use this skill when the user explicitly asks for HTTP API access, when an endpoint is not exposed as an MCP tool, or when running in an environment where direct REST calls are the appropriate bridge.
MoviePilot REST API
All script paths are relative to this skill file.
Use scripts/mp-api.py to call any MoviePilot REST API endpoint directly.
Generic media requests use one stable identity contract: media_source is a
MediaSource enum value and media_id is that source's native ID. Supply the
pair together and keep it unchanged across detail, search, subscription,
download, transfer, scraping, and library checks. Source-specific IDs exposed
by MediaInfo are mapping metadata, not alternate generic request parameters.
Native IDs remain valid on explicitly source-owned endpoints under /tmdb,
/douban, /bangumi, and /anilist.
Scope And Boundaries
This skill is the REST API bridge. It is implemented as a Python script and is
useful when the agent needs endpoint-level coverage beyond the local
moviepilot tool MCP CLI.
Choose other skills first when they match more precisely:
Request
Preferred skill
Normal local MoviePilot product operation exposed as an MCP tool
moviepilot-cli
Direct SQL query or database update
database-operation
Restart, version check, or upgrade
moviepilot-update
Slash commands or plugin/system command dispatch
command-dispatch
Browser-only state, site login pages, screenshots, cookies
browser-use
Do not use this skill just because MoviePilot is mentioned. Use it when the
task specifically needs a REST endpoint, token-query endpoint, or API behavior
that the CLI/MCP tools do not expose.
Setup
When the script runs inside the MoviePilot project, it imports app.runtime.config.settings and reads settings.HOST, settings.PORT, and settings.API_TOKEN directly. Do not ask the user for API_TOKEN, and do not copy API keys into the prompt.
Use configure only as a legacy fallback outside the MoviePilot project, and avoid it in normal agent workflows because it persists a long-lived API key to disk.
By default, the script auto-loads the local key and sends it via the X-API-KEY header.
For endpoints suffixed with 2 (e.g. /api/v1/dashboard/statistic2), use --token-param to send the key as ?token=.
Both methods validate against the same API_TOKEN value.
Never print, summarize, or ask the user to paste the API key unless the script is being used outside the local project and no safer configuration source is available.
API versions and response envelopes
/api/v1 is the only MoviePilot application REST API version; the former
/api/v2 wrapping layer is no longer available.
Every ordinary JSON endpoint returns exactly
{"success":<boolean>,"message":<string>,"data":<endpoint data>}. Only the
data schema varies between endpoints, and the concrete envelope is visible
in /docs and /api/v1/openapi.json.
HTTP errors keep their status code and use success=false; validation errors
include their structured details in data.
Send X-MoviePilot-Locale: zh-CN|zh-TW|en-US or Accept-Language when the
response message must match a specific language. The backend returns the
translated text directly in message and falls back to the original text
when no translation exists.
SSE, files, images, HTML, empty responses, OAuth2 login, and OpenAI,
Anthropic, or MCP JSON-RPC protocol endpoints keep their protocol-native
response body and explicit OpenAPI declaration.
Examples
# GET with query params
python scripts/mp-api.py GET /api/v1/media/search title="Avatar"type="media"# POST with JSON body
python scripts/mp-api.py POST /api/v1/download/add --json '{"torrent_in":{"title":"Avatar.2009","enclosure":"abc1234:1"},"media_source":"themoviedb","media_id":"19995"}'# DELETE
python scripts/mp-api.py DELETE /api/v1/subscribe/123
# Endpoints that require ?token= auth
python scripts/mp-api.py GET /api/v1/dashboard/statistic2 --token-param
# Uniform v1 JSON response envelope
python scripts/mp-api.py GET /api/v1/dashboard/cpu
Complete API Reference
All endpoints are under the base URL {MP_HOST}. Path parameters are shown as {param}.
Media Search (13 endpoints)
When recognition omits media_source, MoviePilot uses TMDB exclusively for video and MusicBrainz exclusively for music. A miss does not trigger another metadata source. Providing media_source, or the complete media_source + media_id pair, keeps recognition strict to that manually selected source.
Method
Path
Description
GET
/api/v1/media/search
Search by title. Params: title (required), `type=media
GET
/api/v1/media/recognize
Recognize media from a torrent title or a media file path. Params: title (required), subtitle, custom_words, optional media_source; media file paths also use parent-directory metadata such as title and year
GET
/api/v1/media/recognize2
Recognize media from a torrent title or media file path (API_TOKEN auth, use --token-param). Params: title, subtitle, custom_words, optional media_source; media file paths also use parent-directory metadata
GET
/api/v1/media/recognize_file
Recognize media from file path. Params: path (required), optional media_source
Save category strategy config. Body: CategoryConfig
GET
/api/v1/media/category
Get auto-categorization config
GET
/api/v1/media/group/seasons/{episode_group}
Get episode group seasons. TMDB-only endpoint
GET
/api/v1/media/groups/{tmdbid}
Get media episode groups. TMDB-only endpoint, so the native ID parameter is intentional
GET
/api/v1/media/seasons
Get media season info. Use media_source + media_id, or title discovery with title and optional year; optional season narrows the result
GET
/api/v1/media/{media_id}
Get media detail by native ID. Required params: media_source, type_name (电影/电视剧)
TMDB (8 endpoints)
Method
Path
Description
GET
/api/v1/tmdb/seasons/{tmdbid}
All seasons for a TMDB title
GET
/api/v1/tmdb/similar/{tmdbid}/{type_name}
Similar movies/TV shows
GET
/api/v1/tmdb/recommend/{tmdbid}/{type_name}
Recommended movies/TV shows
GET
/api/v1/tmdb/collection/{collection_id}
Collection details. Params: page, count
GET
/api/v1/tmdb/credits/{tmdbid}/{type_name}
Cast and crew. Params: page
GET
/api/v1/tmdb/person/{person_id}
Person details
GET
/api/v1/tmdb/person/credits/{person_id}
Person's filmography. Params: page
GET
/api/v1/tmdb/{tmdbid}/{season}
All episodes of a season. Params: episode_group
Douban (5 endpoints)
Method
Path
Description
GET
/api/v1/douban/{doubanid}
Douban media detail
GET
/api/v1/douban/person/{person_id}
Person detail
GET
/api/v1/douban/person/credits/{person_id}
Person filmography. Params: page
GET
/api/v1/douban/credits/{doubanid}/{type_name}
Cast info (type_name: movie/tv)
GET
/api/v1/douban/recommend/{doubanid}/{type_name}
Recommendations
Bangumi (5 endpoints)
Method
Path
Description
GET
/api/v1/bangumi/{bangumiid}
Bangumi detail
GET
/api/v1/bangumi/credits/{bangumiid}
Cast. Params: page, count
GET
/api/v1/bangumi/recommend/{bangumiid}
Recommendations. Params: page, count
GET
/api/v1/bangumi/person/{person_id}
Person detail
GET
/api/v1/bangumi/person/credits/{person_id}
Person filmography. Params: page, count
AniList (8 endpoints)
AniList endpoints prefer the anilist-chinese proxy and fall back to official AniList GraphQL plus the project's daily translation dataset when the public proxy is unavailable. Media titles prefer the provided Chinese title and fall back to the native-language title.
Music uses the independent MusicMeta / MusicInfo contract and a
source-native MusicBrainz identity. music_type=recording is one track,
album is a multi-track collection, and artist is browse-only. MoviePilot
searches, recognizes, subscribes to, downloads, organizes, scrapes, and checks
music on configured music-capable media servers; it does not manage playlists.
Method
Path
Description
GET
/api/v1/media/search
Search tracks, albums, or artists with type=music or a music media_source. Params: title, type, count, repeated enum media_source
POST
/api/v1/music/recognize
Resolve music metadata. Body: media_source, media_id
GET
/api/v1/music/explore
Explore by media_source: MusicBrainz supports `mode=chart
GET
/api/v1/music/album/{album_id}
Album detail with tracks and releases. Params: media_source
GET
/api/v1/music/album/{album_id}/related
Related albums for the selected source. Params: media_source, count
GET
/api/v1/music/artist/{artist_id}
Browse artist detail. Params: media_source
GET
/api/v1/music/artist/{artist_id}/albums
Browse artist albums/EPs/singles. Params: media_source, page, count, album_type
GET
/api/v1/music/artist/{artist_id}/related
Browse related artists. Params: media_source, count
Music acquisition rules:
Reuse media_source, media_id, and music_type from search/detail results. Never substitute a same-name entity.
Subscribe/download one recording as one track. Subscribe/download one album as a complete multi-track pack.
Album torrent validation compares supported audio files with total_tracks; incomplete resources do not complete the subscription.
Artist IDs are never subscription, torrent, download, transfer, or library-existence targets.
/api/v1/media/scrape/{storage} writes configured music tags/covers and can fetch LRCLIB lyrics as .lrc/.txt sidecars. External metadata, cover, exploration, statistics, and lyrics requests use bounded TTL/LRU caches in their owning modules/helpers.
Search / Torrents / Subtitles (11 endpoints)
Method
Path
Description
GET
/api/v1/search/media/{media_id}
Search torrents by native ID. Required param: media_source; other params: mtype, area, season, sites, music_type
GET
/api/v1/search/media/{media_id}/stream
Stream torrent search by native ID with SSE. Required param: media_source; other params match the non-streaming endpoint
Fuzzy search site subtitles by keyword. Params: keyword, page, sites
GET
/api/v1/search/subtitle/title/stream
Stream fuzzy site subtitle search with SSE. Params: keyword, page, sites
GET
/api/v1/search/subtitle/media/{media_id}
Exact subtitle search by native ID. Required param: media_source; other params: mtype, season, episode, sites
GET
/api/v1/search/subtitle/media/{media_id}/stream
Stream exact subtitle search by native ID with SSE. Required param: media_source; other params match the non-streaming endpoint
GET
/api/v1/search/last
Get latest search results
GET
/api/v1/search/last/context
Get latest search results with replayable params. params.result_type is torrent or subtitle
POST
/api/v1/search/recommend
AI recommended resources. Body: filtered_indices, check_only, force
Streaming search sends {"type":"heartbeat"} every 15 seconds without business events; use it only to keep the connection alive. Final replace payloads above 48 items are batched: the first event uses type=replace, later events use type=append, and every batch includes replace_batch=true, zero-based batch_index, batch_count, and final total_items. Collect all batches in order and replace the visible result atomically. After a replace, the final done event omits duplicate items.
Download (8 endpoints)
Method
Path
Description
GET
/api/v1/download/
List active downloads. Params: name (downloader name); linked history adds media type and source site_name
POST
/api/v1/download/
Add download (with media info). Body: JSON
POST
/api/v1/download/add
Add download without media info. Body: torrent_in, optional paired media_source + media_id, music_type, downloader, save_path; an unrecognized video or music resource returns data.requires_confirmation=true, and the same request may be retried with allow_unrecognized=true after explicit user confirmation
POST
/api/v1/download/subtitle
Download subtitle file to the recognized media download directory. Body: subtitle_in, required media_source + media_id, optional save_path
GET
/api/v1/download/start/{hashString}
Resume download task
GET
/api/v1/download/stop/{hashString}
Pause download task
GET
/api/v1/download/clients
List available download clients
DELETE
/api/v1/download/{hashString}
Delete download task. Params: name
Subscribe (28 endpoints)
Method
Path
Description
GET
/api/v1/subscribe/
List all subscriptions
POST
/api/v1/subscribe/
Add subscription. An explicit identity is always media_source + media_id; music also requires type=音乐 and `music_type=recording
PUT
/api/v1/subscribe/
Update subscription. Body: Subscribe JSON
GET
/api/v1/subscribe/list
List subscriptions (API_TOKEN auth, use --token-param)
GET
/api/v1/subscribe/{subscribe_id}
Subscription detail
DELETE
/api/v1/subscribe/{subscribe_id}
Delete subscription
PUT
/api/v1/subscribe/status/{subid}
Update subscription status. Params: state (required)
List configured active sites compatible with movie, tv, or music searches
POST
/api/v1/site/
Add site. Body: Site JSON
PUT
/api/v1/site/
Update site. Body: Site JSON
GET
/api/v1/site/{site_id}
Site detail by ID
DELETE
/api/v1/site/{site_id}
Delete site
GET
/api/v1/site/domain/{site_url}
Site detail by domain
GET
/api/v1/site/cookiecloud
Sync CookieCloud
GET
/api/v1/site/reset
Reset sites
POST
/api/v1/site/priorities
Batch update site priorities. Body: array
POST
/api/v1/site/cookie/{site_id}
Update site cookie & UA. Body: SiteCookieUpdate JSON
GET
/api/v1/site/cookie/{site_id}
Legacy update site cookie & UA. Params: username, password, code
POST
/api/v1/site/userdata/{site_id}
Refresh site user data
GET
/api/v1/site/userdata/{site_id}
Get site user data. Params: workdate
GET
/api/v1/site/userdata/latest
All sites latest user data
GET
/api/v1/site/test/{site_id}
Test site connection
GET
/api/v1/site/icon/{site_id}
Site icon
GET
/api/v1/site/category/{site_id}
Site categories
GET
/api/v1/site/resource/{site_id}
Site resources. Params: keyword, cat, page
GET
/api/v1/site/statistic/{site_url}
Specific site statistics
GET
/api/v1/site/statistic
All site statistics
GET
/api/v1/site/rss
RSS subscription sites
GET
/api/v1/site/auth
Check authenticated sites
POST
/api/v1/site/auth
Authenticate a site. Body: SiteAuth
GET
/api/v1/site/mapping
Site domain-to-name mapping
GET
/api/v1/site/supporting
Supported site list
History (5 endpoints)
Method
Path
Description
GET
/api/v1/history/download
Download history, newest first. Params: page, count. poster is the poster image; legacy image is the backdrop image.
DELETE
/api/v1/history/download
Delete download history. Body: DownloadHistory JSON
GET
/api/v1/history/transfer
Transfer history, including src_storage and dest_storage for path labels. Params: title, page, count, status
DELETE
/api/v1/history/transfer
Delete transfer history. Params: deletesrc, deletedest. Body: TransferHistory
GET
/api/v1/history/empty/transfer
Clear all transfer history
Media Server (8 endpoints)
Method
Path
Description
GET
/api/v1/mediaserver/play/{itemid}
Play media online
GET
/api/v1/mediaserver/exists
Check if media exists in the local library database. A completed miss is success=true with an empty data.item. Params: media_source + media_id, or title discovery; optional year, mtype, season
Latest library items. Params: server (required), count
GET
/api/v1/mediaserver/playing
Currently playing. Params: server (required), count
GET
/api/v1/mediaserver/library
Library list. Params: server (required), hidden
GET
/api/v1/mediaserver/clients
Available media servers
Notification (1 endpoint)
Method
Path
Description
POST
/api/v1/notification/manage
Unified notification-channel management. Body: ManageRequest JSON {target, action, params}; target is the channel name, action is one of status, refresh_qrcode, logout, test_connection, migrate_cache, params carries channel-specific form fields passed through to the channel module
Storage / Files (7 endpoints)
Method
Path
Description
POST
/api/v1/storage/manage
Unified storage management. Body: ManageRequest JSON {target, action, params}; target is the storage type, action is one of save_config (config in params.conf), reset_config, generate_qrcode, generate_auth_url, check_login (params.ck/params.t), usage, support_transtype
POST
/api/v1/storage/list
List directory contents. Params: sort. Body: FileItem JSON
POST
/api/v1/storage/mkdir
Create directory. Params: name (required). Body: FileItem
Preview transfer name. Params: path (required), filetype (required)
GET
/api/v1/transfer/queue
Transfer queue
DELETE
/api/v1/transfer/queue
Remove from transfer queue. Body: FileItem JSON
POST
/api/v1/transfer/manual/target-path
Match the manual transfer target from source path and directory configuration. Body: ManualTransferItem JSON; this endpoint does not recognize media
POST
/api/v1/transfer/manual/history
Query successful transfer-history summary for selected files or directories. Body: ManualTransferItem JSON
POST
/api/v1/transfer/manual
Manual transfer. Params: background. Body: ManualTransferItem JSON; optional media_source + media_id select recognition and scraping source; matching failed history is cleared automatically, while reorganize=true removes matched successful history and old non-move targets before retrying
GET
/api/v1/transfer/now
Run immediate transfer
Dashboard (19 endpoints)
Method
Path
Description
GET
/api/v1/dashboard/statistic
Media statistics. Params: name
GET
/api/v1/dashboard/statistic2
Media statistics (API_TOKEN, use --token-param)
GET
/api/v1/dashboard/storage
Local storage space
GET
/api/v1/dashboard/storage2
Local storage space (API_TOKEN)
GET
/api/v1/dashboard/processes
Process info
GET
/api/v1/dashboard/system
Host name, operating system, MoviePilot runtime, and backend version
GET
/api/v1/dashboard/downloader
Downloader info. Params: name
GET
/api/v1/dashboard/downloader2
Downloader info (API_TOKEN)
GET
/api/v1/dashboard/schedule
Scheduled services
GET
/api/v1/dashboard/schedule2
Scheduled services (API_TOKEN)
GET
/api/v1/dashboard/schedule/{job_id}/progress
Scheduled service real-time progress
GET
/api/v1/dashboard/schedule2/{job_id}/progress
Scheduled service real-time progress (API_TOKEN)
GET
/api/v1/dashboard/transfer
Transfer statistics. Params: days
GET
/api/v1/dashboard/cpu
CPU usage
GET
/api/v1/dashboard/cpu2
CPU usage (API_TOKEN)
GET
/api/v1/dashboard/memory
Memory usage
GET
/api/v1/dashboard/memory2
Memory usage (API_TOKEN)
GET
/api/v1/dashboard/network
Network traffic
GET
/api/v1/dashboard/network2
Network traffic (API_TOKEN)
Plugin (25 endpoints)
Method
Path
Description
GET
/api/v1/plugin/
List plugins. Params: state (installed/market/all), force
Re-identify torrent. Optional paired params: media_source, media_id; music may also pass music_type
Recognition Cache (3 endpoints)
The list endpoint returns local cache totals plus shared_recognized and
shared_recognize_enabled for the persisted successful shared-recognition count.
Method
Path
Description
GET
/api/v1/tmdb/cache
Get TheMovieDb recognition cache statistics
DELETE
/api/v1/tmdb/cache/{cache_key}
Delete one URL-encoded TheMovieDb recognition cache key
Upload avatar. Body: multipart/form-data; original filename is returned in data.filename
GET
/api/v1/user/config/{key}
Get user config
POST
/api/v1/user/config/{key}
Update user config
Login (3 endpoints)
Method
Path
Description
POST
/api/v1/login/access-token
Get JWT access token. Body: form (username, password)
GET
/api/v1/login/wallpaper
Login page wallpaper; URL is returned in data
GET
/api/v1/login/wallpapers
Login page wallpaper list
MCP Tools (6 endpoints)
Method
Path
Description
POST
/api/v1/mcp
MCP JSON-RPC 2.0 endpoint
DELETE
/api/v1/mcp
Terminate MCP session
GET
/api/v1/mcp/tools
List all exposed tools
POST
/api/v1/mcp/tools/call
Call a tool. Body: {"tool_name":"...","arguments":{...}}
GET
/api/v1/mcp/tools/{tool_name}
Get tool definition
GET
/api/v1/mcp/tools/{tool_name}/schema
Get tool input schema
The exposed tool list is dynamic: it includes tools declared by enabled plugins
and is refreshed lazily after plugin startup, shutdown, reload, or configuration
activation. Clients that cache MCP metadata must request tools/list again or
reconnect after a plugin lifecycle change.
Agent MCP Client (3 endpoints)
Method
Path
Description
GET
/api/v1/message/agent/mcp/servers
List external MCP servers configured for the built-in Agent. Superuser login required
POST
/api/v1/message/agent/mcp/servers
Save external MCP servers for the built-in Agent. Body: {"servers":[...]}
POST
/api/v1/message/agent/mcp/servers/test
Test one external MCP server and return discovered tools. Body: {"server":{...}}
Webhook (2 endpoints)
Method
Path
Description
GET
/api/v1/webhook/
Webhook message (GET). Params: token, source
POST
/api/v1/webhook/
Webhook message (POST). Params: token, source
Servarr Compatibility -- /api/v3 (16 endpoints)
Radarr/Sonarr compatible API for integration with external tools.
Method
Path
Description
GET
/api/v3/system/status
System status
GET
/api/v3/qualityProfile
Quality profiles
GET
/api/v3/rootfolder
Root folders
GET
/api/v3/tag
Tags
GET
/api/v3/languageprofile
Languages
GET
/api/v3/movie
All subscribed movies
POST
/api/v3/movie
Add movie subscription. Body: RadarrMovie JSON
GET
/api/v3/movie/lookup
Search movie. Params: term (format: tmdb:123)
GET
/api/v3/movie/{mid}
Movie detail
DELETE
/api/v3/movie/{mid}
Delete movie subscription
GET
/api/v3/series
All TV series
POST
/api/v3/series
Add TV subscription. Body: SonarrSeries JSON
PUT
/api/v3/series
Update TV subscription. Body: SonarrSeries JSON
GET
/api/v3/series/lookup
Search TV. Params: term (format: tvdb:123)
GET
/api/v3/series/{tid}
TV detail
DELETE
/api/v3/series/{tid}
Delete TV subscription
CookieCloud -- /cookiecloud (5 endpoints)
Method
Path
Description
GET
/cookiecloud/
Root
POST
/cookiecloud/
Root
POST
/cookiecloud/update
Upload cookie data. Body: CookieData JSON
GET
/cookiecloud/get/{uuid}
Download encrypted data
POST
/cookiecloud/get/{uuid}
Download encrypted data (POST)
Common Workflows
Search and download a movie
# 1. Search TMDB for the movie
python scripts/mp-api.py GET /api/v1/media/search title="Inception"type="media"# 2. Get media detail with the exact identity returned by search
python scripts/mp-api.py GET /api/v1/media/27205 media_source="themoviedb"type_name="电影"# 3. Search torrents
python scripts/mp-api.py GET /api/v1/search/media/27205 media_source="themoviedb"mtype="movie"# 4. Get latest search results
python scripts/mp-api.py GET /api/v1/search/last
# 5. Add download
python scripts/mp-api.py POST /api/v1/download/add --json '{"torrent_in":{"title":"<title_from_search>","enclosure":"<url_from_search>"},"media_source":"themoviedb","media_id":"27205"}'
Search and subscribe to one recording or complete album
# 1. Search MusicBrainz entities through the unified media search
python scripts/mp-api.py GET /api/v1/media/search title="Artist - Title"type="music"count=20# 2a. For an album, inspect its complete track list before subscribing
python scripts/mp-api.py GET /api/v1/music/album/<album_mbid> media_source="musicbrainz"# 2b. Check the exact entity subscription separately; music_type prevents recording/album ambiguity
python scripts/mp-api.py GET /api/v1/subscribe/media/<mbid> media_source="musicbrainz"music_type="album"# 3. Add one exact album subscription. REST enum values use the localized MediaType value.
python scripts/mp-api.py POST /api/v1/subscribe/ --json '{"name":"Album Title","type":"音乐","music_type":"album","media_source":"musicbrainz","media_id":"<album_mbid>"}'# For one track, use that track's recording MBID and music_type=recording instead.
Do not create an artist subscription. Select a recording or album from the artist catalog first. For an album manual download, use one matched album resource; the download layer rejects resources whose audio-file list does not cover total_tracks.
Search and download subtitles
# 1. Search site subtitles by keyword
python scripts/mp-api.py GET /api/v1/search/subtitle/title keyword="Inception"sites="1,2"# 2. Restore the last subtitle search with replayable params
python scripts/mp-api.py GET /api/v1/search/last/context
# 3. Download a subtitle result to the recognized media directory
python scripts/mp-api.py POST /api/v1/download/subtitle --json '{"subtitle_in":{"title":"Inception.2010.1080p.chs","enclosure":"https://example.com/downloadsubs.php?torrentid=1&subid=2","site_name":"Example"},"media_source":"themoviedb","media_id":"27205"}'
Add a subscription
# 1. Search for the show
python scripts/mp-api.py GET /api/v1/media/search title="Breaking Bad"type="media"# 2. Check if already subscribed
python scripts/mp-api.py GET /api/v1/subscribe/media/1396 media_source="themoviedb"# 3. Check if already in library
python scripts/mp-api.py GET /api/v1/mediaserver/exists media_source="themoviedb"media_id=1396mtype="tv"# 4. Add subscription
python scripts/mp-api.py POST /api/v1/subscribe/ --json '{"name":"Breaking Bad","year":"2008","type":"电视剧","media_source":"themoviedb","media_id":"1396"}'
System monitoring
# CPU, memory, network
python scripts/mp-api.py GET /api/v1/dashboard/cpu
python scripts/mp-api.py GET /api/v1/dashboard/memory
python scripts/mp-api.py GET /api/v1/dashboard/network
# Storage
python scripts/mp-api.py GET /api/v1/dashboard/storage
# Active downloads
python scripts/mp-api.py GET /api/v1/download/
# Run a scheduled task
python scripts/mp-api.py GET /api/v1/system/runscheduler jobid="subscribe_search_all"
Site management
# List all sites
python scripts/mp-api.py GET /api/v1/site/
# Test site connectivity
python scripts/mp-api.py GET /api/v1/site/test/1
# Get site user data
python scripts/mp-api.py GET /api/v1/site/userdata/1
# Sync CookieCloud
python scripts/mp-api.py GET /api/v1/site/cookiecloud
Error Handling
Scenario
Action
HTTP 401
API key is invalid or missing. Verify local settings with moviepilot doctor; only use --apikey as an external fallback.
HTTP 403
Insufficient permissions. The API key grants superuser access; check if the endpoint requires special auth.
HTTP 404
Endpoint or resource not found. Verify the path and path parameters.
HTTP 422
Validation error. Check required parameters and JSON body format.
Connection error
Verify --host URL is reachable. Check if MoviePilot is running.
Missing config
Run inside the MoviePilot project, or set MP_HOST and MP_API_KEY in the process environment.
