Plex Butler API
The butler is responsible for running periodic tasks. Some tasks run daily, others every few days, and some weekly. These includes database maintenance, metadata updating, thumbnail generation, media analysis, and other tasks.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/plex-butler-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Plex Media Server Butler API
version: '1.2.2
'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
description: '# API Info
## Content Types
The API supports responses in both XML and JSON, and clients can request one or the other using the standard `Accept` HTTP header.'
servers:
- url: https://{IP-description}.{identifier}.plex.direct:{port}
variables:
IP-description:
default: 1-2-3-4
description: A `-` separated string of the IPv4 or IPv6 address components
identifier:
default: 0123456789abcdef0123456789abcdef
description: The unique identifier of this particular PMS
port:
default: '32400'
security:
- user_token:
- shared user
- admin
tags:
- name: Butler
description: The butler is responsible for running periodic tasks. Some tasks run daily, others every few days, and some weekly. These includes database maintenance, metadata updating, thumbnail generation, media analysis, and other tasks.
paths:
/butler:
get:
tags:
- Butler
security:
- user_token:
- admin
summary: Get all Butler tasks
description: Get the list of butler tasks and their scheduling
operationId: butlerGetSlash
responses:
'200':
description: Butler tasks
content:
application/json:
schema:
type: object
properties:
ButlerTasks:
type: object
properties:
ButlerTask:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the task
interval:
type: integer
description: The interval (in days) of when this task is run. A value of 1 is run every day, 7 is every week, etc.
scheduleRandomized:
type: boolean
description: Indicates whether the timing of the task is randomized within the butler interval
enabled:
type: boolean
description: Whether this task is enabled or not
title:
type: string
description: A user-friendly title of the task
description:
type: string
description: A user-friendly description of the task
examples:
tasks:
description: Example tasks
value:
ButlerTasks:
ButlerTask:
- name: AutomaticUpdates
interval: 1
scheduleRandomized: false
enabled: false
- name: BackupDatabase
interval: 3
scheduleRandomized: false
enabled: true
title: Backup Database
description: Create a backup copy of the server's database in the configured backup directory
- name: ButlerTaskGenerateAdMarkers
interval: 1
scheduleRandomized: false
enabled: false
- name: ButlerTaskGenerateCreditsMarkers
interval: 1
scheduleRandomized: true
enabled: true
- name: ButlerTaskGenerateIntroMarkers
interval: 1
scheduleRandomized: false
enabled: true
- name: ButlerTaskGenerateVoiceActivity
interval: 1
scheduleRandomized: true
enabled: true
- name: CleanOldBundles
interval: 7
scheduleRandomized: false
enabled: true
- name: CleanOldCacheFiles
interval: 7
scheduleRandomized: false
enabled: true
- name: DeepMediaAnalysis
interval: 1
scheduleRandomized: false
enabled: true
- name: GarbageCollectBlobs
interval: 7
scheduleRandomized: false
enabled: true
- name: GarbageCollectLibraryMedia
interval: 1
scheduleRandomized: false
enabled: true
- name: GenerateBlurHashes
interval: 1
scheduleRandomized: false
enabled: true
- name: GenerateChapterThumbs
interval: 1
scheduleRandomized: false
enabled: true
- name: GenerateMediaIndexFiles
interval: 1
scheduleRandomized: false
enabled: false
- name: LoudnessAnalysis
interval: 1
scheduleRandomized: false
enabled: true
- name: MusicAnalysis
interval: 1
scheduleRandomized: false
enabled: true
- name: OptimizeDatabase
interval: 7
scheduleRandomized: false
enabled: true
- name: RefreshEpgGuides
interval: 1
scheduleRandomized: true
enabled: true
- name: RefreshLibraries
interval: 1
scheduleRandomized: false
enabled: false
- name: RefreshLocalMedia
interval: 3
scheduleRandomized: false
enabled: true
- name: RefreshPeriodicMetadata
interval: 1
scheduleRandomized: true
enabled: true
- name: UpgradeMediaAnalysis
interval: 1
scheduleRandomized: false
enabled: true
post:
tags:
- Butler
security:
- user_token:
- admin
summary: Start all Butler tasks
description: 'This endpoint will attempt to start all Butler tasks that are enabled in the settings. Butler tasks normally run automatically during a time window configured on the server''s Settings page but can be manually started using this endpoint. Tasks will run with the following criteria:
1. Any tasks not scheduled to run on the current day will be skipped.
2. If a task is configured to run at a random time during the configured window and we are outside that window, the task will start immediately.
3. If a task is configured to run at a random time during the configured window and we are within that window, the task will be scheduled at a random time within the window.
4. If we are outside the configured window, the task will start immediately.'
operationId: butlerPostSlash
responses:
'200':
$ref: '#/components/responses/200'
delete:
tags:
- Butler
security:
- user_token:
- admin
summary: Stop all Butler tasks
description: This endpoint will stop all currently running tasks and remove any scheduled tasks from the queue.
operationId: butlerDeleteSlash
responses:
'200':
$ref: '#/components/responses/200'
/butler/{task}:
post:
tags:
- Butler
security:
- user_token:
- admin
summary: Start a single Butler task
description: This endpoint will attempt to start a specific Butler task by name.
operationId: butlerPostTask
parameters:
- in: path
name: task
schema:
type: string
enum:
- AutomaticUpdates
- BackupDatabase
- ButlerTaskGenerateAdMarkers
- ButlerTaskGenerateCreditsMarkers
- ButlerTaskGenerateIntroMarkers
- ButlerTaskGenerateVoiceActivity
- CleanOldBundles
- CleanOldCacheFiles
- DeepMediaAnalysis
- GarbageCollectBlobs
- GarbageCollectLibraryMedia
- GenerateBlurHashes
- GenerateChapterThumbs
- GenerateMediaIndexFiles
- LoudnessAnalysis
- MusicAnalysis
- OptimizeDatabase
- RefreshEpgGuides
- RefreshLibraries
- RefreshLocalMedia
- RefreshPeriodicMetadata
- UpgradeMediaAnalysis
description: The task name
required: true
responses:
'200':
description: Task started
content:
text/html:
examples:
ok:
summary: OK
value: ''
'202':
description: Task is already running
content:
text/html:
examples:
ok:
summary: OK
value: ''
'404':
description: No task with this name was found
content:
text/html:
examples:
notFound:
summary: Not Found
value: <html><head><title>Not Found</title></head><body><h1>404 Not Found</h1></body></html>
delete:
tags:
- Butler
security:
- user_token:
- admin
summary: Stop a single Butler task
description: This endpoint will stop a currently running task by name, or remove it from the list of scheduled tasks if it exists
operationId: butlerDeleteTask
parameters:
- in: path
name: task
schema:
type: string
enum:
- AutomaticUpdates
- BackupDatabase
- ButlerTaskGenerateAdMarkers
- ButlerTaskGenerateCreditsMarkers
- ButlerTaskGenerateIntroMarkers
- ButlerTaskGenerateVoiceActivity
- CleanOldBundles
- CleanOldCacheFiles
- DeepMediaAnalysis
- GarbageCollectBlobs
- GarbageCollectLibraryMedia
- GenerateBlurHashes
- GenerateChapterThumbs
- GenerateMediaIndexFiles
- LoudnessAnalysis
- MusicAnalysis
- OptimizeDatabase
- RefreshEpgGuides
- RefreshLibraries
- RefreshLocalMedia
- RefreshPeriodicMetadata
- UpgradeMediaAnalysis
description: The task name
required: true
responses:
'200':
$ref: '#/components/responses/200'
'404':
description: No task with this name was found or no task with this name was running
content:
text/html:
examples:
notFound:
summary: Not Found
value: <html><head><title>Not Found</title></head><body><h1>404 Not Found</h1></body></html>
components:
responses:
'200':
description: OK
content:
text/html:
examples:
ok:
summary: OK
value: ''
securitySchemes:
user_token:
type: apiKey
in: header
name: X-Plex-Token
description: The token which identifies the user accessing the PMS. This is typically provided to the client by plex.tv. This can be either a traditional access token or a JWT token obtained through the JWT authentication flow.
x-tagGroups:
- name: General
tags:
- General
- Library
- Library Playlists
- Library Collections
- Status
- Activities
- Updater
- Butler
- Events
- Log
- Preferences
- Download Queue
- UltraBlur
- Transcoder
- name: Media Provider
tags:
- Provider
- Metadata Agents
- Content
- Hubs
- Search
- Rate
- Playlist
- Play Queue
- Timeline
- name: DVR
tags:
- DVRs
- Devices
- EPG
- Subscriptions
- Live TV