Plex Metadata Agents API

openapi: 3.2.0
info:
  title: Plex Media Server Metadata Agents 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: Metadata Agents
paths:
  /media/providers/metadata:
    get:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: getMetadataAgentProviders
      summary: Get the list of available metadata agent providers
      description: Get the list of all available metadata agent providers for this PMS.
      parameters:
      - in: query
        name: metadataTypes
        required: false
        schema:
          type: array
          items:
            type: integer
          example: 1,2,3,4
        description: A comma-separated list of metadata types to filter the providers by. If not specified, all providers are returned.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        MetadataAgentProvider:
                          type: array
                          items:
                            $ref: '#/components/schemas/metadataAgentProvider'
              examples:
                Themoviedb Metadata Provider:
                  value:
                    MediaContainer:
                      size: 1
                      MetadataAgentProvider:
                      - id: '1'
                        identifier: tv.plex.agents.custom.themoviedb
                        title: The Movie Database
                        uri: http://localhost/themoviedb/api
                        agentType: primary
                        MetadataType:
                        - type: 1
                        - type: 2
                        - type: 3
                        - type: 4
                        online: true
    post:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: postMetadataAgentProviders
      summary: Add a metadata agent provider
      description: This endpoint registers a metadata agent provider with the server. The provider URI must respond with a valid MediaProvider response.
      parameters:
      - in: query
        name: uri
        required: true
        schema:
          type: string
        description: The URI of the metadata agent provider to add.
      responses:
        '200':
          $ref: '#/components/responses/metadataAgentProviderManager_slash-get-responses-200'
        '400':
          $ref: '#/components/responses/400'
        '409':
          description: A provider with the same identifier already exists
          $ref: '#/components/responses/409'
  /media/providers/metadata/{providerId}:
    get:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: getMetadataAgentProvider
      summary: Get a metadata agent provider
      description: Get the metadata agent provider with the given id.
      parameters:
      - in: path
        name: providerId
        schema:
          type: integer
        description: The ID of the metadata agent provider to get
        required: true
      responses:
        '200':
          $ref: '#/components/responses/metadataAgentProviderManager_slash-get-responses-200'
        '404':
          $ref: '#/components/responses/404'
    put:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: putMetadataAgentProvider
      summary: Modify a metadata agent provider
      description: Modify the metadata agent provider with the given id. Only the URI is passed, the response to the URI will determine the other properties.
      parameters:
      - in: path
        name: providerId
        schema:
          type: integer
        description: The ID of the metadata agent provider to modify
        required: true
      - in: query
        name: uri
        schema:
          type: string
        description: The new URI of the metadata agent provider.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        MetadataAgentProvider:
                          type: array
                          items:
                            $ref: '#/components/schemas/metadataAgentProvider'
              examples:
                Themoviedb Metadata Provider:
                  value:
                    MediaContainer:
                      size: 1
                      MetadataAgentProvider:
                      - id: '1'
                        identifier: tv.plex.agents.custom.themoviedb
                        title: The Movie Database
                        uri: http://localhost/themoviedb/api
                        agentType: primary
                        MetadataType:
                        - type: 1
                        - type: 2
                        - type: 3
                        - type: 4
                        online: true
        '400':
          $ref: '#/components/responses/400'
    delete:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: deleteMetadataAgentProvider
      summary: Delete a metadata agent provider
      description: Deletes a metadata agent provider with the given id. This will fail if the provider is being used inside a MetadataAgentGroup.
      parameters:
      - in: path
        name: providerId
        schema:
          type: integer
        description: The ID of the metadata agent provider to delete
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '403':
          description: Cannot delete a provider which is currently used inside a group.
          content:
            text/html:
              examples:
                forbidden:
                  summary: Forbidden
                  value: <html><head><title>Forbidden</title></head><body><h1>403 Forbidden</h1></body></html>
        '404':
          $ref: '#/components/responses/404'
  /media/providers/metadata/group:
    get:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: getMetadataAgentProviderGroups
      summary: Get the list of available metadata agent provider groups
      description: Get the list of all available metadata agent provider groups for this PMS.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        MetadataAgentProviderGroup:
                          type: array
                          items:
                            $ref: '#/components/schemas/metadataAgentProviderGroup'
              examples:
                Themoviedb Metadata Provider:
                  value:
                    MediaContainer:
                      size: 1
                      MetadataAgentProviderGroup:
                      - id: '1'
                        title: TheMovieDatabase
                        primaryIdentifier: tv.plex.agents.custom.themoviedb
                        MetadataAgentProviderGroupItem:
                        - id: '1'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '6'
                          order: 1000
                        - id: '2'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '7'
                          order: 2000
                        - id: '3'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '8'
                          order: 3000
    post:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: postMetadataAgentProviderGroups
      summary: Add a metadata agent provider group
      description: This endpoint registers a new metadata agent provider group and creates a new MetadataAgentGroupItem for the primraryIdentifier.
      parameters:
      - in: query
        name: title
        required: true
        schema:
          type: string
        description: The title of the metadata agent provider group to add.
      - in: query
        name: primaryIdentifier
        required: true
        schema:
          type: string
        description: The identifier of the metadata agent provider which will be the primary for the group.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        MetadataAgentProviderGroup:
                          type: array
                          items:
                            $ref: '#/components/schemas/metadataAgentProviderGroup'
              examples:
                Themoviedb Metadata Provider:
                  value:
                    MediaContainer:
                      size: 1
                      MetadataAgentProviderGroup:
                      - id: '1'
                        title: TheMovieDatabase
                        primaryIdentifier: tv.plex.agents.custom.themoviedb
                        MetadataAgentProviderGroupItem:
                        - id: '1'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '6'
                          order: 1000
                        - id: '2'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '7'
                          order: 2000
                        - id: '3'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '8'
                          order: 3000
        '400':
          $ref: '#/components/responses/400'
  /media/providers/metadata/group/{groupId}:
    get:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: getMetadataAgentProviderGroup
      summary: Get a metadata agent provider group
      description: Get the metadata agent provider group with the given id.
      parameters:
      - in: path
        name: groupId
        schema:
          type: integer
        description: The ID of the metadata agent provider group to get
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        MetadataAgentProviderGroup:
                          type: array
                          items:
                            $ref: '#/components/schemas/metadataAgentProviderGroup'
              examples:
                Themoviedb Metadata Provider:
                  value:
                    MediaContainer:
                      size: 1
                      MetadataAgentProviderGroup:
                      - id: '1'
                        title: TheMovieDatabase
                        primaryIdentifier: tv.plex.agents.custom.themoviedb
                        MetadataAgentProviderGroupItem:
                        - id: '1'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '6'
                          order: 1000
                        - id: '2'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '7'
                          order: 2000
                        - id: '3'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '8'
                          order: 3000
        '404':
          $ref: '#/components/responses/404'
    put:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: putMetadataAgentProviderGroup
      summary: Modify a metadata agent provider group
      description: Modify the metadata agent group with the given id. Only the title can be changed.
      parameters:
      - in: path
        name: groupId
        schema:
          type: integer
        description: The ID of the metadata agent provider group to update
        required: true
      - in: query
        name: title
        schema:
          type: string
        description: The title of the metadata agent provider group to update.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        MetadataAgentProviderGroup:
                          type: array
                          items:
                            $ref: '#/components/schemas/metadataAgentProviderGroup'
              examples:
                Themoviedb Metadata Provider:
                  value:
                    MediaContainer:
                      size: 1
                      MetadataAgentProviderGroup:
                      - id: '1'
                        title: TheMovieDatabase
                        primaryIdentifier: tv.plex.agents.custom.themoviedb
                        MetadataAgentProviderGroupItem:
                        - id: '1'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '6'
                          order: 1000
                        - id: '2'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '7'
                          order: 2000
                        - id: '3'
                          metadataAgentProviderGroupId: '3'
                          metadataAgentProviderId: '8'
                          order: 3000
        '400':
          $ref: '#/components/responses/400'
    delete:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: deleteMetadataAgentProviderGroup
      summary: Delete a metadata agent provider group
      description: Deletes a metadata agent provider group with the given id. This will also delete any MetadataAgentGroupItem objects associated with the group.
      parameters:
      - in: path
        name: groupId
        schema:
          type: integer
        description: The ID of the metadata agent provider group to delete
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200'
        '404':
          $ref: '#/components/responses/404'
  /media/providers/metadata/group/{groupId}/items/{providerId}:
    put:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: putMetadataAgentProviderGroupItem
      summary: Modify a metadata agent provider group's items
      description: 'Modify a metadata agent provider group''s items. This will assign the specified provider id to the group if it does not already exist.


        Providing the optional after query parameter on an existing group item will move its position in the group relative to the item with the specified ID.'
      parameters:
      - in: path
        name: groupId
        schema:
          type: integer
        description: The ID of the metadata agent group
        required: true
      - in: path
        name: providerId
        schema:
          type: integer
        description: The ID of the metadata agent provider
        required: true
      - in: query
        name: after
        schema:
          type: number
        description: The ID of the group item to place this item after. This only works if the group item already exists. A -1 value will place the item at the beginning.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  MediaContainer:
                    allOf:
                    - $ref: '#/components/schemas/MediaContainer'
                    - type: object
                      properties:
                        MetadataAgentProviderGroupItem:
                          type: array
                          items:
                            $ref: '#/components/schemas/metadataAgentProviderGroupItem'
              examples:
                Example Provider Group Item:
                  value:
                    MediaContainer:
                      size: 1
                      MetadataAgentProviderGroupItem:
                      - id: '1'
                        metadataAgentProviderGroupId: '3'
                        metadataAgentProviderId: '6'
                        order: 1000
        '400':
          $ref: '#/components/responses/400'
    delete:
      tags:
      - Metadata Agents
      security:
      - user_token:
        - admin
      operationId: deleteMetadataAgentProviderGroupItem
      summary: Delete a metadata agent provider group item
      description: Deletes a metadata agent provider group item with the given id.
      parameters:
      - in: path
        name: groupId
        schema:
          type: integer
        description: The ID of the metadata agent provider group
        required: true
      - in: path
        name: providerId
        schema:
          type: integer
        description: The ID of the metadata agent provider
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200'
        '403':
          description: Cannot delete the primary provider of a group.
          content:
            text/html:
              examples:
                forbidden:
                  summary: Forbidden
                  value: <html><head><title>Forbidden</title></head><body><h1>403 Forbidden</h1></body></html>
        '404':
          $ref: '#/components/responses/404'
components:
  schemas:
    metadataAgentProviderGroupItem:
      description: 'Sub-items of a MetadataAgentProviderGroup object. They represent specific MetadataAgentProvider objects.

        '
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the item.
        metadataAgentProviderGroupId:
          type: integer
          description: The unique identifier for the MetadataAgentProviderGroup.
        metadataAgentProviderId:
          type: integer
          description: The unique identifier for the MetadataAgentProvider.
        order:
          type: number
          description: The order of the item in the group.
    metadataAgentProviderGroup:
      description: 'An item that describes a group of MetadataAgentProviderGroupItem objects.

        '
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the item.
        title:
          type: string
          description: The title of the group.
        primaryIdentifier:
          type: string
          description: The primary identifier for the group. i.e. the identifier of the MetadataAgentProvider which will provide the item guids.
        MetadataAgentGroupItem:
          type: array
          items:
            $ref: '#/components/schemas/metadataAgentProviderGroupItem'
    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
    metadataAgentProvider:
      description: 'Describes a MetadataAgentProvider object.

        '
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the item.
        identifier:
          type: string
          description: The identifier for the provider.
        title:
          type: string
          description: The title of the provider.
        uri:
          type: string
          description: The URI of the provider.
        agentType:
          type: string
          description: 'The type of agent.

            - primary: A metadata provider which provides a unique identifier (guid) for each item.

            - contributor: A metadata provider which provides additional metadata for items but does not have a unique item identifier.

            '
          enum:
          - primary
          - contributor
        MetadataType:
          type: array
          items:
            type: object
            properties:
              type:
                type: integer
                description: The type of supported metadata.
          description: The metadata types supported by the provider.
        online:
          type: boolean
          description: Indicates whether the provider is online.
  responses:
    '409':
      description: Conflict
      content:
        text/html:
          examples:
            conflict:
              summary: Conflict
              value: <html><head><title>Conflict</title></head><body><h1>409 Conflict</h1></body></html>
    '404':
      description: 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>
    metadataAgentProviderManager_slash-get-responses-200:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              MediaContainer:
                allOf:
                - $ref: '#/components/schemas/MediaContainer'
                - type: object
                  properties:
                    MetadataAgentProvider:
                      type: array
                      items:
                        $ref: '#/components/schemas/metadataAgentProvider'
          examples:
            Themoviedb Metadata Provider:
              value:
                MediaContainer:
                  size: 1
                  MetadataAgentProvider:
                  - id: '1'
                    identifier: tv.plex.agents.custom.themoviedb
                    title: The Movie Database
                    uri: http://localhost/themoviedb/api
                    agentType: primary
                    MetadataType:
                    - type: 1
                    - type: 2
                    - type: 3
                    - type: 4
                    online: true
    '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