Plex Media Server OpenAPI Specification

An Open Source OpenAPI Specification for Plex Media Server

Automation and SDKs provided by Speakeasy

Documentation

API Documentation

SDKs

The following SDKs are generated from the OpenAPI Specification. They are automatically generated and may not be fully tested. If you find any issues, please open an issue on the respective repository.

Language	Repository	Releases	Other
Python	GitHub	PyPI	-
JavaScript/TypeScript	GitHub	NPM \ JSR	-
Go	GitHub	Releases	GoDoc
Ruby	GitHub	Releases	-
Swift	GitHub	Releases	-
PHP	GitHub	Releases	-
Java	GitHub	Releases	-
C#	GitHub	Releases	-

Project Structure

The main OpenAPI Specification is located in the root directory as pms-spec.yaml. Which references

• /paths: The endpoints for the Plex Media Server API. Each endpoint is defined in a separate file.
• /models: The schema models used in the specification.
• /parameters: The parameters used in the specification.
• /responses: The responses used in the specification.

In addition, there is a bundled single file OpenAPI Specification, plex-media-server-spec-dereferenced.yaml which is automatically bundled on any changes to the main specification.

Style Guide

All spec files should adhere to the 3.1 OpenAPI Specification.

Reference documentation can be found Here and Here.

Every endpoint is defined in the /paths directory, with Each endpoint defined in a separate file. The file name should be the endpoint name with the method type. For example, the endpoint /library/sections is defined in the file /paths/library_sections.get.yaml.

The file should contain data in the following order:

[get/post/put/delete]:
  servers: # only specify if the endpoint requires a different server than the users plex server
  security: # only specify if the endpoint requires authentication different from the global security
  tags: 
    - example # a list of tags that the endpoint belongs to, this is used for grouping in the documentation and SDKs
  summary: a brief description of the endpoint
  description: a more detailed description of the endpoint
  operationId: anExampleOperationId # camel case summarizing the action being performed.
  parameters: # parameters are defined in the /parameters directory, or inline if they are not reused very much
    - $ref: "../../parameters/..." # a reference to a parameter file in the /parameters directory
    - name: example # a parameter that is not a reference
      in: query # the location of the parameter, can be query, path, header, or cookie
      description: an example parameter
      required: true # whether the parameter is required or not, path parameters are always required. Only specify this key if the parameter is required
      schema:
        type: string
  responses:
    2XX:
      $ref: "../../responses/..." # a reference to a response file in the /responses directory
    4XX:
    5XX:

Headers

Plex Media Server accept a variety of custom headers that follow the pattern X-Plex-{name}.

The full set of headers isn't enumerated here since some may only apply to certain endpoints, but common headers that can be included on all requests include:

Header	Description	Sample
X-Plex-Client-Identifier	An opaque identifier unique to the client	abc123
X-Plex-Token	An authentication token, obtained from plex.tv	XXXXXXXXXXXX
X-Plex-Product	The name of the client product	Plex for Roku
X-Plex-Version	The version of the client application	2.4.1
X-Plex-Platform	The platform of the client	Roku
X-Plex-Platform-Version	The version of the platform	4.3 build 1057
X-Plex-Device	A relatively friendly name for the client device	Roku 3
X-Plex-Model	A potentially less friendly identifier for the device model	4200X
X-Plex-Device-Vendor	The device vendor	Roku
X-Plex-Device-Name	A friendly name for the client	Living Room TV
X-Plex-Marketplace	The marketplace on which the client application is distributed	googlePlay

X-Plex-Client-Identifier is typically required, as is X-Plex-Token for authentication.

Rules

• A property in the response is only marked as required if it is always returned, regardless of the parameters sent with the request.
• Although Plex.tv API uses the X-Plex-Token as a query parameter, this specification will always define this as a header parameter where supported since this follows industry security standards.
• Though Plex does default return XML unless the accept header is set to application/json, this specification will not include the accept header in the endpoints. Assume it should always be included in the request.
• Parameters added to endpoints via reference should always be specified at the bottom of the paramters set, since there is a large set of common parameters that are used across all endpoints.

Questions?

Reach out to me on the Discord Server