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.
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.core.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.
Examples
# GET with query params
python scripts/mp-api.py GET /api/v1/media/search title="Avatar"type="movie"# POST with JSON body
python scripts/mp-api.py POST /api/v1/download/add --json '{"torrent_url":"abc1234:1"}'# 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
Complete API Reference
All endpoints are under the base URL {MP_HOST}. Path parameters are shown as {param}.
Media Search (13 endpoints)
Method
Path
Description
GET
/api/v1/media/search
Search media, collections, or people by title. Params: title (required), type, page, count, optional source. Supported sources: media = themoviedb, douban, bangumi, anilist; collection = themoviedb; person = themoviedb, douban
GET
/api/v1/media/recognize
Recognize media from torrent title. Params: title (required), subtitle, custom_words, optional source
GET
/api/v1/media/recognize2
Recognize media (API_TOKEN auth, use --token-param). Params: title, subtitle, custom_words, optional source
GET
/api/v1/media/recognize_file
Recognize media from file path. Params: path (required), optional 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
GET
/api/v1/media/groups/{tmdbid}
Get media episode groups
GET
/api/v1/media/seasons
Get media season info. Params: mediaid, title, year, season
GET
/api/v1/media/{mediaid}
Get media detail. mediaid supports tmdb:, douban:, bangumi:, anilist:, and plugin-defined source prefixes. Params: type_name (required: movie/tv), title, year
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.
Search torrents by media ID (four built-in prefixes or a plugin-defined source prefix). Params: mtype, area, title, year, season, sites
GET
/api/v1/search/media/{mediaid}/stream
Stream torrent search by media ID with SSE. Params: mtype, area, title, year, season, sites
GET
/api/v1/search/title
Fuzzy search torrents by keyword. Params: keyword, page, sites
GET
/api/v1/search/title/stream
Stream fuzzy torrent search with SSE. Params: keyword, page, sites
GET
/api/v1/search/subtitle/title
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/{mediaid}
Exact subtitle search by media ID (four built-in prefixes or a plugin-defined source prefix). Params: mtype, title, year, season, episode, sites
GET
/api/v1/search/subtitle/media/{mediaid}/stream
Stream exact subtitle search by media ID with SSE. Params: mtype, title, year, season, episode, sites
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)
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 media_source + media_id (all four dedicated IDs remain supported), downloader, save_path
POST
/api/v1/download/subtitle
Download subtitle file to the recognized media download directory. Body: subtitle_in, optional media_source + media_id (all four dedicated IDs remain supported), 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. Body accepts media_source + media_id and compatible tmdbid, doubanid, bangumiid, anilistid fields
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)
GET
/api/v1/subscribe/media/{mediaid}
Query subscription by a built-in or plugin-prefixed media ID. Params: season, title
DELETE
/api/v1/subscribe/media/{mediaid}
Delete subscription by a built-in or plugin-prefixed media ID. Params: season
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 manual transfer target path. Body: ManualTransferItem JSON; optional media_source + media_id select the recognition source
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
The two list endpoints return 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
DELETE
/api/v1/tmdb/cache
Clear TheMovieDb recognition cache
GET
/api/v1/douban/cache
Get Douban recognition cache statistics
DELETE
/api/v1/douban/cache/{cache_key}
Delete one URL-encoded Douban recognition cache key
Get JWT access token. Body: form (username, password)
GET
/api/v1/login/wallpaper
Login page wallpaper
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="movie"# 2. Get media detail (replace {tmdbid} with actual ID)
python scripts/mp-api.py GET /api/v1/media/27205 type_name="movie"# 3. Search torrents
python scripts/mp-api.py GET /api/v1/search/media/tmdb:27205 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_url":"<url_from_search>"}'
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"},"tmdbid":27205}'
Add a subscription
# 1. Search for the show
python scripts/mp-api.py GET /api/v1/media/search title="Breaking Bad"type="tv"# 2. Check if already subscribed
python scripts/mp-api.py GET /api/v1/subscribe/media/tmdb:1396
# 3. Check if already in library
python scripts/mp-api.py GET /api/v1/mediaserver/exists tmdbid=1396mtype="tv"# 4. Add subscription
python scripts/mp-api.py POST /api/v1/subscribe/ --json '{"name":"Breaking Bad","year":"2008","type":"tv","tmdbid":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.
