Server topic

Read the server's identity and settings, follow its background work and administer it.

Identity and info

final id = await plex.server.identity();
print('${id.machineIdentifier} ${id.version} claimed=${id.claimed}');

final info = await plex.server.info();
print('${info.friendlyName} ${info.version} on ${info.platform}');
print('Plex Pass: ${info.myPlexSubscription}, '
    'sonic analysis: ${info.musicAnalysis}');

if (await plex.server.ping()) { /* reachable */ }

identity() needs no token, so it checks a server URL before you sign in again. info() adds friendlyName, platform, platformVersion, myPlex, myPlexUsername, musicAnalysis, transcoderAudio, transcoderLyrics, allowSync, countryCode and updatedAt. ping() returns false instead of throwing; call identity() to see why a server is unreachable.

Activities, butler tasks and settings

final running = await plex.activities.list(); // List<PlexActivity>
for (final a in running) {
  print('${a.title} ${a.progress ?? 0}% cancellable=${a.cancellable}');
}
final scan = running.where((a) => a.cancellable).firstOrNull;
if (scan != null) await plex.activities.cancel(activityId: scan.uuid);

final tasks = await plex.butler.tasks(); // List<PlexButlerTask>
await plex.butler.start(butlerTask: tasks.first.name);

final settings = await plex.preferences.all(); // List<PlexSetting>
final name = await plex.preferences.byId(id: 'FriendlyName');
await plex.preferences.set({'FriendlyName': 'Living room'});
print('${settings.length} settings, previous name ${name?.value}');

butler.stop(), startAll() and stopAll() control the other maintenance tasks.

Administration

These calls need an admin token.

Call Does
server.backgroundTasks() Background transcode jobs (optimizing, converting for download), as PlexTranscodeJob
server.transientToken() Issues a short-lived delegation token, for a cast target or a viewer link
server.securityResources(source:) Connection info and token for a source, for cross-server playback (PlexSecurityResource)
log.writeMessage(level:, message:, source:) Writes one line to the server log; level is 0 (error) to 4 (verbose)
log.writeBlock(body:) Appends a multi-line body to the server log
log.enablePapertrail(minutes:) Forwards the log to Papertrail for a while
updater.status(), check(), apply() Server software updates (PlexUpdaterStatus, with its releases); apply(tonight: true) waits for the quiet hours
providers.list(), add(url:), refresh(), delete(provider:) Media providers registered on the server (PlexMediaProvider, with its features)

Classes

PlexActivitiesApi Server
/activities — long-running server activities (scan progress, transcoding sessions, etc.).
PlexActivity Server
A running background activity (/activities → Activity), e.g. a library scan. The same activities arrive live as PlexActivityEvents.
PlexButlerApi Server
/butler — Plex's nightly maintenance task runner.
PlexButlerTask Server
A scheduled maintenance task (/butler → ButlerTask).
PlexLogApi Server
/log — send log entries to the server.
PlexMediaProvider Server
A media provider registered on the server (/media/providers): the library itself, or an online source.
PlexPreferencesApi Server
/:/prefs — server preferences (setting names and values).
PlexProviderFeature Server
One feature of a PlexMediaProvider (Feature).
PlexProvidersApi Server
/media/providers — third-party media providers (TIDAL, internal channels, external streaming sources).
PlexRelease Server
A server release on offer (Release).
PlexSecurityResource Server
How to reach a source and with which token (/security/resources).
PlexServerApi Server
Top-level server endpoints — /, /identity, /capabilities.
PlexServerIdentity Server
GET /identity — who the server is. Answers without a token.
PlexServerInfo Server
GET / — the server's capabilities and account state.
PlexSetting Server
One server preference (/:/prefs → Setting).
PlexTranscodeJob Server
A background transcode job — an optimize or a sync conversion (/status/sessions/background, TranscodeJob).
PlexUpdaterApi Server
/updater/* — server software update lifecycle.
PlexUpdaterStatus Server
The server's update state (/updater/status).