plexjava/docs/sdks/butler/README.md

Butler

(butler())

Overview

Butler is the task manager of the Plex Media Server Ecosystem.

Available Operations

• getButlerTasks - Get Butler tasks
• startAllTasks - Start all Butler tasks
• stopAllTasks - Stop all Butler tasks
• startTask - Start a single Butler task
• stopTask - Stop a single Butler task

getButlerTasks

Returns a list of butler tasks

Example Usage

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.GetButlerTasksResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            GetButlerTasksResponse res = sdk.butler().getButlerTasks()
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (dev.plexapi.sdk.models.errors.GetButlerTasksBadRequest e) {
            // handle exception
            throw e;
        } catch (dev.plexapi.sdk.models.errors.GetButlerTasksUnauthorized e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Response

GetButlerTasksResponse

Errors

Error Object	Status Code	Content Type
models/errors/GetButlerTasksBadRequest	400	application/json
models/errors/GetButlerTasksUnauthorized	401	application/json
models/errors/SDKError	4xx-5xx	*/*

startAllTasks

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.

Example Usage

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.StartAllTasksResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            StartAllTasksResponse res = sdk.butler().startAllTasks()
                .call();

            // handle response
        } catch (dev.plexapi.sdk.models.errors.StartAllTasksBadRequest e) {
            // handle exception
            throw e;
        } catch (dev.plexapi.sdk.models.errors.StartAllTasksUnauthorized e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Response

StartAllTasksResponse

Errors

Error Object	Status Code	Content Type
models/errors/StartAllTasksBadRequest	400	application/json
models/errors/StartAllTasksUnauthorized	401	application/json
models/errors/SDKError	4xx-5xx	*/*

stopAllTasks

This endpoint will stop all currently running tasks and remove any scheduled tasks from the queue.

Example Usage

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.StopAllTasksResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            StopAllTasksResponse res = sdk.butler().stopAllTasks()
                .call();

            // handle response
        } catch (dev.plexapi.sdk.models.errors.StopAllTasksBadRequest e) {
            // handle exception
            throw e;
        } catch (dev.plexapi.sdk.models.errors.StopAllTasksUnauthorized e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Response

StopAllTasksResponse

Errors

Error Object	Status Code	Content Type
models/errors/StopAllTasksBadRequest	400	application/json
models/errors/StopAllTasksUnauthorized	401	application/json
models/errors/SDKError	4xx-5xx	*/*

startTask

This endpoint will attempt to start a single Butler task that is 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.

Example Usage

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.StartTaskResponse;
import dev.plexapi.sdk.models.operations.TaskName;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            StartTaskResponse res = sdk.butler().startTask()
                .taskName(TaskName.CLEAN_OLD_BUNDLES)
                .call();

            // handle response
        } catch (dev.plexapi.sdk.models.errors.StartTaskBadRequest e) {
            // handle exception
            throw e;
        } catch (dev.plexapi.sdk.models.errors.StartTaskUnauthorized e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter	Type	Required	Description
taskName	TaskName	✔️	the name of the task to be started.

Response

StartTaskResponse

Errors

Error Object	Status Code	Content Type
models/errors/StartTaskBadRequest	400	application/json
models/errors/StartTaskUnauthorized	401	application/json
models/errors/SDKError	4xx-5xx	*/*

stopTask

This endpoint will stop a currently running task by name, or remove it from the list of scheduled tasks if it exists. See the section above for a list of task names for this endpoint.

Example Usage

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.PathParamTaskName;
import dev.plexapi.sdk.models.operations.StopTaskResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            StopTaskResponse res = sdk.butler().stopTask()
                .taskName(PathParamTaskName.BACKUP_DATABASE)
                .call();

            // handle response
        } catch (dev.plexapi.sdk.models.errors.StopTaskBadRequest e) {
            // handle exception
            throw e;
        } catch (dev.plexapi.sdk.models.errors.StopTaskUnauthorized e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter	Type	Required	Description
taskName	PathParamTaskName	✔️	The name of the task to be started.

Response

StopTaskResponse

Errors

Error Object	Status Code	Content Type
models/errors/StopTaskBadRequest	400	application/json
models/errors/StopTaskUnauthorized	401	application/json
models/errors/SDKError	4xx-5xx	*/*