pms-spec.yaml

openapi: 3.1.0
info:
  version: 0.0.3
  title: Plex-API
  summary: An Open API Spec for interacting with Plex.tv and Plex Media Server
  description: |
    # Plex Media Server OpenAPI Specification

    An Open Source OpenAPI Specification for Plex Media Server

    Automation and SDKs provided by [Speakeasy](https://speakeasyapi.dev/)

    ## Documentation

    [API Documentation](https://plexapi.dev)

    ## 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 [main specification Repository](https://github.com/LukeHagar/plex-api-spec).

    | Language              | Repository                                        | Releases                                                                                         | Other                                                   |
    | --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
    | Python                | [GitHub](https://github.com/LukeHagar/plexpy)     | [PyPI](https://pypi.org/project/plex-api-client/)                                                | -                                                       |
    | JavaScript/TypeScript | [GitHub](https://github.com/LukeHagar/plexjs)     | [NPM](https://www.npmjs.com/package/@lukehagar/plexjs) \ [JSR](https://jsr.io/@lukehagar/plexjs) | -                                                       |
    | Go                    | [GitHub](https://github.com/LukeHagar/plexgo)     | [Releases](https://github.com/LukeHagar/plexgo/releases)                                         | [GoDoc](https://pkg.go.dev/github.com/LukeHagar/plexgo) |
    | Ruby                  | [GitHub](https://github.com/LukeHagar/plexruby)   | [Releases](https://github.com/LukeHagar/plexruby/releases)                                       | -                                                       |
    | Swift                 | [GitHub](https://github.com/LukeHagar/plexswift)  | [Releases](https://github.com/LukeHagar/plexswift/releases)                                      | -                                                       |
    | PHP                   | [GitHub](https://github.com/LukeHagar/plexphp)    | [Releases](https://github.com/LukeHagar/plexphp/releases)                                        | -                                                       |
    | Java                  | [GitHub](https://github.com/LukeHagar/plexjava)   | [Releases](https://github.com/LukeHagar/plexjava/releases)                                       | -                                                       |
    | C#                    | [GitHub](https://github.com/LukeHagar/plexcsharp) | [Releases](https://github.com/LukeHagar/plexcsharp/releases)                                     | -
  contact:
    name: Luke Hagar
    url: "https://www.LukeHagar.com"
    email: Lukeslakemail@gmail.com
  license:
    url: "https://opensource.org/license/mit"
    name: MIT

servers:
  - url: "{protocol}://{ip}:{port}"
    description: The full address of your Plex Server
    variables:
      protocol:
        default: "https"
        description: The protocol to use for the server connection
        enum:
          - "http"
          - "https"
      ip:
        default: "10.10.10.47"
        description: The IP address or hostname of your Plex Server
      port:
        default: "32400"
        description: The port of your Plex Server

x-speakeasy-globals:
  parameters:
    - $ref: "./parameters/plex/x-plex-identifier.yaml"
    - $ref: "./parameters/plex/x-plex-product.yaml"
    - $ref: "./parameters/plex/x-plex-version.yaml"
    - $ref: "./parameters/plex/x-plex-platform.yaml"
    - $ref: "./parameters/plex/x-plex-device.yaml"

security:
  - accessToken: []

components:
  securitySchemes:
    accessToken:
      description: Plex Authentication Token
      type: apiKey
      in: header
      name: X-Plex-Token

paths:
  # Plex Media Server endpoints

  # Colon Endpoints
  # Folder: pms/paths/colon
  /:
    $ref: "./paths/colon/colon.yaml"
  /:/prefs:
    $ref: "./paths/colon/prefs.yaml"
  /:/scrobble:
    $ref: "./paths/colon/scrobble.yaml"
  /:/unscrobble:
    $ref: "./paths/colon/unscrobble.yaml"
  /:/progress:
    $ref: "./paths/colon/progress.yaml"
  /:/timeline:
    $ref: "./paths/colon/timeline.yaml"

  # Activities
  # Folder: pms/paths/activities
  /activities:
    $ref: "./paths/activities/activities.yaml"
  /activities/{activityUUID}:
    $ref: "./paths/activities/cancel.yaml"

  # Butler
  # Folder: pms/paths/butler
  /butler:
    $ref: "./paths/butler/butler.yaml"
  /butler/{taskName}:
    $ref: "./paths/butler/task.yaml"

  /clients:
    $ref: "./paths/clients.yaml"
  /devices:
    $ref: "./paths/devices.yaml"

  # Companions
  # Folder pms/paths/companions
  /companions:
    $ref: "paths/companions/companions.yaml"

  # Friends
  # Folder pms/paths/friends
  /friends:
    $ref: "paths/friends/friends.yaml"

  # GeoIP
  # Folder pms/paths/geoip
  /geoip:
    $ref: "paths/geoip/geoip.yaml"

  # Plex Home
  # Folder: pms/paths/home
  /home:
    $ref: "./paths/home.yaml"

  # Hubs
  # Folder: pms/paths/hubs
  /hubs:
    $ref: "./paths/hubs/hubs.yaml"
  /hubs/home/recentlyAdded:
    $ref: "./paths/hubs/home/get-recently-added.yaml"
  /hubs/search:
    $ref: "./paths/hubs/search.yaml"
  /hubs/search/voice:
    $ref: "./paths/hubs/search-voice.yaml"
  /hubs/sections/{sectionId}:
    $ref: "./paths/hubs/section.yaml"

  /identity:
    $ref: "./paths/identity/identity.yaml"

  # Library
  # Folder: pms/paths/library
  /library/hashes:
    $ref: "./paths/library/hashes.yaml"
  /library/recentlyAdded:
    $ref: "./paths/library/get-recently-added.yaml"
  /library/sections:
    $ref: "./paths/library/get-all-libraries.yaml"

  /library/sections/{sectionKey}:
    $ref: "./paths/library/[sectionKey]/library-section.yaml"

  # Watchlist
  /library/sections/watchlist/{filter}:
    $ref: "./paths/library/sections/watchlist/get-watch-list.yaml"

  /library/sections/{sectionKey}/{tag}:
    $ref: "./paths/library/[sectionKey]/get-library-items.yaml"
  /library/sections/{sectionKey}/refresh:
    $ref: "./paths/library/[sectionKey]/refresh/get-refresh-library-metadata.yaml"
  /library/sections/{sectionKey}/search:
    $ref: "./paths/library/[sectionKey]/get-search-library.yaml"

  /library/search:
    $ref: "./paths/library/get-search-all-libraries.yaml"

  /library/metadata/{ratingKey}:
    $ref: "./paths/library/metadata/[ratingKey]/get-meta-data-by-rating-key.yaml"
  /library/metadata/{ratingKey}/banner:
    $ref: "./paths/library/metadata/[ratingKey]/banner/get-banner-image.yaml"
  /library/metadata/{ratingKey}/thumb:
    $ref: "./paths/library/metadata/[ratingKey]/thumb/get-thumb-image.yaml"
  /library/metadata/{ratingKey}/children:
    $ref: "./paths/library/metadata-children.yaml"
  /library/all/top:
    $ref: "./paths/library/content-top.yaml"
  /library/onDeck:
    $ref: "./paths/library/ondeck.yaml"

  # Resources
  # Folder: pms/resources
  /resources:
    $ref: "./paths/resources/get-server-resources.yaml"

  # Logs
  # Folder: pms/paths/logs
  /log:
    $ref: "./paths/logs/log.yaml"
  /log/networked:
    $ref: "./paths/logs/networked.yaml"

  /myplex/account:
    $ref: "./paths/myplex-account.yaml"

  /photo/:/transcode:
    $ref: "./paths/photo-transcode.yaml"

  # Pins
  # Folder: pms/paths/pins
  /pins:
    $ref: "./paths/pins/pins.yaml"
  /pins/{pinID}:
    $ref: "./paths/pins/pins-id.yaml"

  # Playlists
  # Folder: pms/paths/playlists
  /playlists:
    $ref: "./paths/playlists/playlists.yaml"
  /playlists/{playlistID}:
    $ref: "./paths/playlists/id.yaml"
  /playlists/{playlistID}/items:
    $ref: "./paths/playlists/contents.yaml"
  /playlists/upload:
    $ref: "./paths/playlists/upload.yaml"

  # Media
  /media/providers:
    $ref: "./paths/media/providers/get-media-providers.yaml"

  /search:
    $ref: "./paths/search.yaml"

  # Authentication
  # Folder: pms/paths/authentication
  /security/token:
    $ref: "./paths/authentication/token.yaml"
  /security/resources:
    $ref: "./paths/authentication/resources.yaml"

  /servers:
    $ref: "./paths/servers.yaml"

  /statistics/media:
    $ref: "./paths/statistics/media.yaml"
  /statistics/resources:
    $ref: "./paths/statistics/resources.yaml"
  /statistics/bandwidth:
    $ref: "./paths/statistics/bandwidth.yaml"

  # Status
  /status/sessions:
    $ref: "./paths/status/sessions.yaml"
  /status/sessions/history/all:
    $ref: "./paths/status/session-history.yaml"

  /transcode/sessions:
    $ref: "./paths/transcode-sessions.yaml"
  /transcode/sessions/{sessionKey}:
    $ref: "./paths/transcode-sessions-key.yaml"

  /updater/status:
    $ref: "./paths/updater/status.yaml"
  /updater/check:
    $ref: "./paths/updater/check.yaml"
  /updater/apply:
    $ref: "./paths/updater/apply.yaml"

  /video/:/transcode/universal/start.mpd:
    $ref: "./paths/video-transcode-universal-start.yaml"

  # User
  /user:
    $ref: "./paths/user/get-user-data-by-token.yaml"

  /users/signin:
    $ref: "./paths/users/post-sign-in.yaml"

tags:
  - name: Activities
    description: |
      Activities are awesome. They provide a way to monitor and control asynchronous operations on the server. In order to receive real-time updates for activities, a client would normally subscribe via either EventSource or Websocket endpoints.
      Activities are associated with HTTP replies via a special `X-Plex-Activity` header which contains the UUID of the activity.
      Activities are optional cancellable. If cancellable, they may be cancelled via the `DELETE` endpoint. Other details:
      - They can contain a `progress` (from 0 to 100) marking the percent completion of the activity.
      - They must contain an `type` which is used by clients to distinguish the specific activity.
      - They may contain a `Context` object with attributes which associate the activity with various specific entities (items, libraries, etc.)
      - The may contain a `Response` object which attributes which represent the result of the asynchronous operation.
  - name: Authentication
    description: |
      API Calls regarding authentication for Plex Media Server
  - name: Butler
    description: |
      Butler is the task manager of the Plex Media Server Ecosystem.
  - name: Server
    description: |
      Operations against the Plex Media Server System.
  - name: Updater
    description: |
      This describes the API for searching and applying updates to the Plex Media Server.
      Updates to the status can be observed via the Event API.
  - name: Log
    description: |
      Submit logs to the Log Handler for Plex Media Server
  - name: Library
    description: |
      API Calls interacting with Plex Media Server Libraries
  - name: Media
    description: |
      API Calls interacting with Plex Media Server Media
  - name: Hubs
    description: |
      Hubs are a structured two-dimensional container for media, generally represented by multiple horizontal rows.
  - name: Playlists
    description: |
      Playlists are ordered collections of media. They can be dumb (just a list of media) or smart (based on a media query, such as "all albums from 2017"). 
      They can be organized in (optionally nesting) folders.
      Retrieving a playlist, or its items, will trigger a refresh of its metadata. 
      This may cause the duration and number of items to change.
  - name: Search
    description: |
      API Calls that perform search operations with Plex Media Server
  - name: Sessions
    description: |
      API Calls that perform search operations with Plex Media Server Sessions
  - name: User
    description: |
      API Calls that perform operations with Plex Media Server Users
  - name: Video
    description: |
      API Calls that perform operations with Plex Media Server Videos
  - name: Plex
    description: |
      API Calls that perform operations directly against https://Plex.tv
  - name: Statistics
    description: |
      API Calls that perform operations with Plex Media Server Statistics
  - name: Watchlist
    description: |
      API Calls that perform operations with Plex Media Server Watchlists