Plex Host API

The Plex Host REST API lets you manage servers, files, backups, and players from your own scripts, bots, or integrations — everything the dashboard can do to a server, an API token can do too, scoped to whatever you grant it.

This page covers the REST API (/api/v1). Plex Host also has a GraphQL API that powers the dashboard itself; it isn't part of this public contract.

Base URL

https://api.host.plex.gg

Every path in this section is relative to that base URL, e.g. GET /api/v1/servers means GET https://api.host.plex.gg/api/v1/servers. Development and staging environments use different hosts — use the base URL your token was issued against.

Authentication

Every request carries an API token as a bearer credential:

Authorization: Bearer plx_srv_...

Tokens come in two kinds, distinguished by their prefix — see Tokens for how to create and manage them:

Prefix	Kind	Scope
`plx_srv_`	Server	Bound to one server; scopes are that server's permissions
`plx_acc_`	Account	Acts across every server the owner can reach; scopes are broader actions like `servers:read`

A token is shown once, at creation. Plex Host stores only its hash.

The response envelope

Every /api/v1 response is wrapped the same way, success or failure.

Success:

{
  "data": { "...": "..." },
  "meta": { "requestId": "req_01hz..." }
}

Failure:

{
  "error": {
    "code": "SCOPE_DENIED",
    "message": "Token is missing the canModifyFiles scope",
    "requestId": "req_01hz...",
    "details": ["optional field-level validation messages"],
    "retryAfterSeconds": 0
  }
}

requestId is also echoed as the X-Request-Id response header — include it when reporting an issue. details is present only on a 400 from request validation; retryAfterSeconds is present only on a 429.

Rate limits

Every response carries rate-limit headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Seconds until the window resets

A request that exceeds the limit gets a 429 with a Retry-After header and retryAfterSeconds in the error body:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "requestId": "req_01hz...",
    "retryAfterSeconds": 42
  }
}

Error codes

Access denied (403):

Code	Meaning
`API_TOKEN_NOT_ALLOWED`	The operation is closed to tokens outright, regardless of scope
`WRONG_SERVER`	A server token was used against a server other than the one it's bound to
`SCOPE_DENIED`	The token's scopes don't cover the capability the operation needs
`OWNER_ONLY`	The operation requires the account owner; no token satisfies it

Quota and plan (403 / 429):

Code	Meaning
`API_DISABLED_FOR_PLAN`	The owner's plan doesn't include API access
`TOKEN_LIMIT_REACHED`	The server already has the maximum number of tokens its plan allows (on creation)
`RATE_LIMITED`	Per-minute request cap hit — retry after `retryAfterSeconds`
`QUOTA_EXCEEDED`	Monthly request cap hit
`PLAN_LIMIT`	The token is suspended because a plan change put its owner over a limit — see Tokens

Scopes

A server token's scopes are the same permissions a team member can hold on that server:

Scope	Grants
`canViewServer`	Read server status, resource stats, and configuration
`canControlServer`	Start, stop, restart, kill, and send console commands
`canViewFiles`	Browse and read files
`canModifyFiles`	Upload, edit, rename, move, and delete files
`canViewBackups`	List backups and view backup details
`canCreateBackups`	Create backups
`canRestoreBackups`	Restore a backup onto the server
`canDeleteBackups`	Delete backups
`canViewPlayers`	See the online player list and player activity
`canManagePlayers`	Announce messages, ban, and unban players
`canViewActivity`	Read the server's activity log

An account token's scopes act across every server the owner can reach, and map onto the same underlying permissions:

Scope	Maps to
`servers:read`	`canViewServer`
`servers:power`	`canControlServer`
`servers:command`	`canControlServer`
`files:read`	`canViewFiles`
`files:write`	`canModifyFiles`
`backups:read`	`canViewBackups`
`backups:create`	`canCreateBackups`
`backups:restore`	`canRestoreBackups`
`backups:delete`	`canDeleteBackups`
`players:read`	`canViewPlayers`
`players:manage`	`canManagePlayers`
`activity:read`	`canViewActivity`

A token's effective access is the intersection of its scopes and whatever the owner can currently do. If an owner is removed from a team, or a team role loses a capability, tokens that relied on it stop working even though the token itself hasn't changed.

Quick start

curl https://api.host.plex.gg/api/v1/servers \
  -H "Authorization: Bearer plx_acc_..."

{
  "data": [
    { "id": "srv_01hz...", "name": "Survival", "status": "running" }
  ],
  "meta": { "requestId": "req_01hz..." }
}

See Tokens to create your first token, then Servers, Files, Backups, and Players for the full operation reference, or Examples for curl, Node, Python, and a Discord bot.

On this page