Plex

Plex Devices API

Media grabbers provide ways for media to be obtained for a given protocol. The simplest ones are `stream` and `download`. More complex grabbers can have associated devices Network tuners can present themselves on the network using the Simple Service Discovery Protocol and Plex Media Server will discover them. The following XML is an example of the data returned from SSDP. The `deviceType`, `serviceType`, and `serviceId` values must remain as they are in the example in order for PMS to properly discover the device. Other less-obvious fields are described in the parameters section below. Example SSDP output ``` 1 0 urn:plex-tv:device:Media:1 Turing Hopper 3000 Plex, Inc. https://plex.tv/ Turing Hopper 3000 Media Grabber Plex Media Grabber 1 https://plex.tv uuid:42fde8e4-93b6-41e5-8a63-12d848655811 http://10.0.0.5:8088 urn:plex-tv:service:MediaGrabber:1 urn:plex-tv:serviceId:MediaGrabber ``` - UDN: (string) A UUID for the device. This should be unique across models of a device at minimum. - URLBase: (string) The base HTTP URL for the device from which all of the other endpoints are hosted.

GitHub OpenAPI

Operations 13

GET /media/grabbers Get available grabbers #
GET /media/grabbers/devices Get all devices #
POST /media/grabbers/devices Add a device #
POST /media/grabbers/devices/discover Tell grabbers to discover devices #
GET /media/grabbers/devices/{deviceId} Get device details #
DELETE /media/grabbers/devices/{deviceId} Remove a device #
PUT /media/grabbers/devices/{deviceId} Enable or disable a device #
PUT /media/grabbers/devices/{deviceId}/channelmap Set a device's channel mapping #
GET /media/grabbers/devices/{deviceId}/channels Get a device's channels #
PUT /media/grabbers/devices/{deviceId}/prefs Set device preferences #
POST /media/grabbers/devices/{deviceId}/scan Tell a device to scan for channels #
DELETE /media/grabbers/devices/{deviceId}/scan Tell a device to stop scanning for channels #
GET /media/grabbers/devices/{deviceId}/thumb/{version} Get device thumb #

Documentation

📖
Documentation
https://developer.plex.tv/pms/
📖
APIReference
https://developer.plex.tv/pms/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/plex/refs/heads/main/openapi/plex-devices-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/plex-devices-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

plex-devices-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Plex Media Server Devices API
  version: '1.2.2

    '
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  description: '# API Info

    ## Content Types

    The API supports responses in both XML and JSON, and clients can request one or the other using the standard `Accept` HTTP header.'
servers:
- url: https://{IP-description}.{identifier}.plex.direct:{port}
  variables:
    IP-description:
      default: 1-2-3-4
      description: A `-` separated string of the IPv4 or IPv6 address components
    identifier:
      default: 0123456789abcdef0123456789abcdef
      description: The unique identifier of this particular PMS
    port:
      default: '32400'
security:
- user_token:
  - shared user
  - admin
tags:
- name: Devices
  description: Media grabbers provide ways for media to be obtained for a given protocol.
paths:
  /media/grabbers:
    get:
      tags:
      - Devices
      summary: Get available grabbers
      description: Get available grabbers visible to the server
      operationId: mediaGrabberGetSlash
      parameters:
      - in: query
        name: protocol
        schema:
          type: string
        example: livetv
        description: Only return grabbers providing this protocol.
      responses:
        '200':
          description: OK
          headers:
            X-Plex-Container-Total-Size:
              description: Provided on all MediaContainer objects indicating the total size of objects available
              schema:
                type: integer
            X-Plex-Container-Start:
              description: Provided on all MediaContainer objects indicating the offset of where this container page starts
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        MediaGrabber:
                          type: array
                          items:
                            type: object
                            properties:
                              title:
                                type: string
                              identifier:
                                type: string
                              protocol:
                                type: string
              examples:
                twoDevices:
                  value:
                    MediaContainer:
                      size: 3
                      MediaGrabber:
                      - identifier: tv.plex.grabbers.hdhomerun
                        protocol: livetv
                        title: HDHomerun
                      - identifier: tv.plex.grabbers.stream
                        protocol: stream
                        title: Stream
                      - identifier: tv.plex.grabbers.download
                        protocol: download
                        title: Download
  /media/grabbers/devices:
    get:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Get all devices
      description: Get the list of all devices present
      operationId: mediaGrabberGetDevices
      responses:
        '200':
          description: OK
          headers:
            X-Plex-Container-Total-Size:
              description: Provided on all MediaContainer objects indicating the total size of objects available
              schema:
                type: integer
            X-Plex-Container-Start:
              description: Provided on all MediaContainer objects indicating the offset of where this container page starts
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaContainerWithDevice'
              examples:
                twoDevices:
                  value:
                    MediaContainer:
                      size: 2
                      Devices:
                      - key: 1053C0CA
                        lastSeenAt: '1461450473'
                        make: Silicondust
                        model: HDHomeRun EXTEND
                        modelNumber: HDTC-2US
                        protocol: livetv
                        tuners: '2'
                        sources: Antenna,Cable
                        uri: http://10.0.0.164
                        uuid: 1053C0CA
                      - key: 141007E7
                        lastSeenAt: '1461450479'
                        make: Silicondust
                        model: HDHomeRun EXPAND
                        modelNumber: HDHR3-4DC
                        protocol: livetv
                        tuners: '4'
                        sources: Cable
                        uri: http://home.techconnect.nl:8822
                        uuid: 141007E7
    post:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Add a device
      description: This endpoint adds a device to an existing grabber. The device is identified, and added to the correct grabber.
      operationId: mediaGrabberPostDevices
      parameters:
      - in: query
        name: uri
        schema:
          type: string
        example: http://10.0.0.5
        description: The URI of the device.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaContainerWithDevice'
              examples:
                addedDevice:
                  value:
                    MediaContainer:
                      size: 1
                      Device:
                      - key: 1053C0CA
                        lastSeenAt: 1461450473
                        make: Silicondust
                        model: HDHomeRun EXTEND
                        modelNumber: HDTC-2US
                        protocol: livetv
                        tuners: '2'
                        uri: http://10.0.0.5
                        uuid: 1053C0CA
        '400':
          $ref: '#/components/responses/400'
  /media/grabbers/devices/discover:
    post:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Tell grabbers to discover devices
      operationId: mediaGrabberPostDeviceDiscover
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaContainerWithDevice'
              examples:
                discoveredDevice:
                  value:
                    MediaContainer:
                      size: 1
                      Device:
                      - key: 1053C0CA
                        lastSeenAt: 1461450473
                        make: Silicondust
                        model: HDHomeRun EXTEND
                        modelNumber: HDTC-2US
                        protocol: livetv
                        tuners: '2'
                        uri: http://10.0.0.164
                        uuid: 1053C0CA
  /media/grabbers/devices/{deviceId}:
    get:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Get device details
      description: Get a device's details by its id
      operationId: mediaGrabberDevicesDeviceGetSlash
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaContainerWithDevice'
              examples:
                discoveredDevice:
                  value:
                    MediaContainer:
                      size: 1
                      Device:
                      - key: '6'
                        lastSeenAt: 1461737032
                        make: Silicondust
                        model: HDHomeRun EXPAND
                        modelNumber: HDHR3-4DC
                        protocol: livetv
                        sources: Cable
                        state: '1'
                        status: '1'
                        tuners: '4'
                        uri: http://home.techconnect.nl:8822
                        uuid: 141007E7
                        ChannelMapping:
                        - channelKey: 5cc83d73af4a72001e9b16d7-5cab3c634df507001fefcad0
                          deviceIdentifier: '46.3'
                          enabled: '1'
                          lineupIdentifier: '002'
                        - channelKey: 5cc83d73af4a72001e9b16d7-5cab3d20d30eca001db32922
                          deviceIdentifier: '48.9'
                          enabled: '0'
                          lineupIdentifier: '004'
                        - channelKey: 5cc83d73af4a72001e9b16d7-5cab3d07771bb2001ef88f72
                          deviceIdentifier: '49.12'
                          enabled: '1'
                          lineupIdentifier: '011'
                        - channelKey: 5cc83d73af4a72001e9b16d7-5cab3c63de29da001cf021c2
                          deviceIdentifier: '49.3'
                          enabled: '0'
                          lineupIdentifier: 008
                        - channelKey: 5cc83d73af4a72001e9b16d7-5cab3c63e3ef4d001d05ba70
                          deviceIdentifier: '10.4'
                          enabled: '1'
        '404':
          description: Device not found
          content:
            text/html:
              examples:
                notFound:
                  summary: Not Found
                  value: <html><head><title>Not Found</title></head><body><h1>404 Not Found</h1></body></html>
    delete:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Remove a device
      description: Remove a devices by its id along with its channel mappings
      operationId: mediaGrabberDevicesDeviceDeleteSlash
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      responses:
        '200':
          description: OK
          headers:
            X-Plex-Container-Total-Size:
              description: Provided on all MediaContainer objects indicating the total size of objects available
              schema:
                type: integer
            X-Plex-Container-Start:
              description: Provided on all MediaContainer objects indicating the offset of where this container page starts
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        message:
                          type: string
                        status:
                          type: integer
              examples:
                discoveredDevice:
                  value:
                    MediaContainer:
                      size: 0
                      message: ''
                      status: 0
        '404':
          description: Device not found
          content:
            text/html:
              examples:
                notFound:
                  summary: Not Found
                  value: <html><head><title>Not Found</title></head><body><h1>404 Not Found</h1></body></html>
    put:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Enable or disable a device
      description: Enable or disable a device by its id
      operationId: mediaGrabberDevicesDevicePutSlash
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      - in: query
        name: enabled
        schema:
          type: integer
          enum:
          - 0
          - 1
        description: Whether to enable the device
      responses:
        '200':
          description: OK
          headers:
            X-Plex-Container-Total-Size:
              description: Provided on all MediaContainer objects indicating the total size of objects available
              schema:
                type: integer
            X-Plex-Container-Start:
              description: Provided on all MediaContainer objects indicating the offset of where this container page starts
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        message:
                          type: string
                        status:
                          type: integer
              examples:
                discoveredDevice:
                  value:
                    MediaContainer:
                      size: 0
                      message: ''
                      status: 0
        '404':
          description: Device not found
          content:
            text/html:
              examples:
                notFound:
                  summary: Not Found
                  value: <html><head><title>Not Found</title></head><body><h1>404 Not Found</h1></body></html>
  /media/grabbers/devices/{deviceId}/channelmap:
    put:
      tags:
      - Devices
      summary: Set a device's channel mapping
      operationId: mediaGrabberDevicesDevicePutChannelmap
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      - in: query
        name: channelMapping
        schema:
          type: object
        style: deepObject
        example:
          '46.3': 2
          '48.9': 4
        description: The mapping of changes, passed as a map of device channel to lineup VCN.
      - in: query
        name: channelMappingByKey
        schema:
          type: object
        style: deepObject
        example:
          '46.3': 5cc83d73af4a72001e9b16d7-5cab3c634df507001fefcad0
          '48.9': 5cc83d73af4a72001e9b16d7-5cab3c63ec158a001d32db8d
        description: The mapping of changes, passed as a map of device channel to lineup key.
      - in: query
        name: channelsEnabled
        schema:
          type: array
          items:
            type: string
        example: 46.1,44.1,45.1
        description: The channels which are enabled.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaContainerWithDevice'
              examples:
                emptyContainer:
                  value:
                    MediaContainer:
                      message: ''
                      size: 0
                      status: 0
  /media/grabbers/devices/{deviceId}/channels:
    get:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Get a device's channels
      description: Get a device's channels by its id
      operationId: mediaGrabberDevicesDeviceGetChannels
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      responses:
        '200':
          description: OK
          headers:
            X-Plex-Container-Total-Size:
              description: Provided on all MediaContainer objects indicating the total size of objects available
              schema:
                type: integer
            X-Plex-Container-Start:
              description: Provided on all MediaContainer objects indicating the offset of where this container page starts
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        DeviceChannel:
                          type: array
                          items:
                            type: object
                            properties:
                              key:
                                type: string
                              identifier:
                                type: string
                              name:
                                type: string
                              drm:
                                type: boolean
                                description: Indicates the channel is DRMed and thus may not be playable
                              hd:
                                type: boolean
                              favorite:
                                type: boolean
                              signalStrength:
                                type: integer
                              signalQuality:
                                type: integer
              examples:
                discoveredDevice:
                  value:
                    MediaContainer:
                      size: 48
                      DeviceChannel:
                      - drm: false
                        hd: false
                        identifier: '46.1'
                        name: KPXO HD
                      - drm: false
                        hd: false
                        identifier: '46.3'
                        name: KHON HD
        '404':
          description: Device not found
          content:
            text/html:
              examples:
                notFound:
                  summary: Not Found
                  value: <html><head><title>Not Found</title></head><body><h1>404 Not Found</h1></body></html>
  /media/grabbers/devices/{deviceId}/prefs:
    put:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Set device preferences
      description: Set device preferences by its id
      operationId: mediaGrabberDevicesDevicePutPrefs
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      - in: query
        name: name
        schema:
          type: string
        description: The preference names and values.
      responses:
        '200':
          $ref: '#/components/responses/200'
  /media/grabbers/devices/{deviceId}/scan:
    post:
      tags:
      - Devices
      summary: Tell a device to scan for channels
      operationId: mediaGrabberDevicesDevicePostScan
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      - in: query
        name: source
        schema:
          type: string
        example: Cable
        description: A valid source for the scan
      responses:
        '200':
          description: OK
          headers:
            X-Plex-Activity:
              schema:
                type: string
              description: The activity of the reload process
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaContainerWithDevice'
              examples:
                emptyContainer:
                  value:
                    MediaContainer:
                      message: ''
                      size: 0
                      status: 0
    delete:
      tags:
      - Devices
      summary: Tell a device to stop scanning for channels
      operationId: mediaGrabberDeleteDevicesDeviceScan
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaContainerWithDevice'
              examples:
                emptyContainer:
                  value:
                    MediaContainer:
                      message: ''
                      size: 0
                      status: 0
  /media/grabbers/devices/{deviceId}/thumb/{version}:
    get:
      tags:
      - Devices
      security:
      - user_token:
        - admin
      summary: Get device thumb
      description: Get a device's thumb for display to the user
      operationId: mediaGrabberDevicesDeviceGetThumbVersion
      parameters:
      - in: path
        name: deviceId
        schema:
          type: integer
        description: The ID of the device.
        required: true
      - in: path
        name: version
        schema:
          type: integer
        description: A version number of the thumb used for busting cache
        required: true
      responses:
        '200':
          description: The thumbnail for the device
        '301':
          description: The thumb URL on the device
        '404':
          description: No thumb found for this device
          content:
            text/html:
              examples:
                notFound:
                  summary: Not Found
                  value: <html><head><title>Not Found</title></head><body><h1>404 Not Found</h1></body></html>
components:
  schemas:
    mediaContainerWithDevice:
      type: object
      properties:
        MediaContainer:
          allOf:
          - $ref: '#/components/schemas/MediaContainer'
          - type: object
            properties:
              Device:
                type: array
                items:
                  type: object
                  properties:
                    key:
                      type: string
                    lastSeenAt:
                      type: integer
                    make:
                      type: string
                    model:
                      type: string
                    modelNumber:
                      type: string
                    protocol:
                      type: string
                    sources:
                      type: string
                    state:
                      type: string
                    status:
                      type: string
                    tuners:
                      type: string
                    uri:
                      type: string
                    uuid:
                      type: string
                    ChannelMapping:
                      type: array
                      items:
                        type: object
                        properties:
                          channelKey:
                            type: string
                          deviceIdentifier:
                            type: string
                          enabled:
                            type: string
                          lineupIdentifier:
                            type: string
    MediaContainer:
      type: object
      properties:
        identifier:
          type: string
        size:
          type: integer
        totalSize:
          type: integer
          description: The total size of objects available.  Also provided in the X-Plex-Container-Total-Size header
        offset:
          type: integer
          description: The offset of where this container page starts among the total objects available.  Also provided in the X-Plex-Container-Start header
  responses:
    '200':
      description: OK
      content:
        text/html:
          examples:
            ok:
              summary: OK
              value: ''
    '400':
      description: Bad Request
      content:
        text/html:
          examples:
            badRequest:
              summary: A parameter has a bad value or required parameter is missing
              value: <html><head><title>Bad Request</title></head><body><h1>400 Bad Request</h1></body></html>
  securitySchemes:
    user_token:
      type: apiKey
      in: header
      name: X-Plex-Token
      description: The token which identifies the user accessing the PMS.  This is typically provided to the client by plex.tv. This can be either a traditional access token or a JWT token obtained through the JWT authentication flow.
x-tagGroups:
- name: General
  tags:
  - General
  - Library
  - Library Playlists
  - Library Collections
  - Status
  - Activities
  - Updater
  - Butler
  - Events
  - Log
  - Preferences
  - Download Queue
  - UltraBlur
  - Transcoder
- name: Media Provider
  tags:
  - Provider
  - Metadata Agents
  - Content
  - Hubs
  - Search
  - Rate
  - Playlist
  - Play Queue
  - Timeline
- name: DVR
  tags:
  - DVRs
  - Devices
  - EPG
  - Subscriptions
  - Live TV